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PREFACE 



Ihe Programmer's Guide to DOMAIN Graphics Primitives describes the DOMAIN* 
graphics primitives system and its user-callable routines. 

Audience 

This manual is written for programmers who use the DOMAIN graphics primitives 
to develop application programs. It is assumed that users of this manual 
have some knowledge of computer graphics and have experience in using the 
DOMAIN system. 

Organization of this Manual 

This manual contains twelve chapters. 

Chapter 1 introduces the graphics primitives systeon and its use on a DOMAIN 
node. 

Chapter 2 describes the display configurations, formats, and modes 
within which the graphics routines can operate. 

Chapter 3 describes bitmap structure and pixels in relation to memory 
representation. The chapter includes discussion of bitmaps 
in display and nain memory, bitmap routines, and bitmap 
attributes. 

Chapter 4 describes the coir^onents and uses of a color map. 

The distinctive characteristics of a color map in imaging format 
are presented. 

Chapter 5 explains the uses of current position and describes drawing, 
filling, and text operations. 

Chapter 6 describes three types of bit block transfers (BLTs) and their uses. 
The differences between calls to the graphics primitives BLTs 
and display driver BLTs are also presented. Examples of BLT 
operations are included. 

Chapter 7 describes the uses of cursor control and of input operations. 
Input operations include routines that enable graphics programs 
to accept input from various input devices such as a keyboard, 
button on a mouse or puck, touchpad, and cursor in a window 
transition. 

* Distributed Operating Multi-Access Interactive Network 
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Chapter 8 describes the routines that graphics programs can call to perform 
direct input and output to windows. A sample program is included 
to show the input and output calls with other GPR routines. 

Chapter 9 lists insert files, data structures with their argument type, 
and error messages. 

Chapter 10 presents sample programs and techniques for using 
graphics primitives. 

Chapter 11 describes graphics primitives routines in terms of format and 
parameters. The routines are organized alpiiabetically. 
A listing by functional category introduces the routines. 

Ch^ter 12 describes grajAiics nap files (GMF) , including insert files, 
data structures, error messages, and user-callable routines. 

i^pendix A illustrates the 880 and low-profile keyboard and keyboard charts 
i^pendices B, C, and D present the insert files for Pascal, C, and FORTE^AN 

Additional Reading 

For information on using the DOMAIN system, see the DOMAIN System Command 
Reference Manual . For information on the software coirponents of the 
operating system and user-callable system routines, see the DOMAIN System 
Prograiiroer's Reference Manual . For language-specific information, see the 
DOMAIN FORTRAN User's Guide and the DOMAIN Pascal User's Guide . For 
information on the high-level language debugger, see the Language Level 
Debugger Manual . 



Documentation Conventions 

Unless otherwise noted in the text, this manual uses the following symbolic 
conventions. 

UPPERCASE Uppercase words or characters in formats and command 
descriptions represent commands or keywords that you must use 
literally. 

lowercase Lowercase words or characters in formats and command 
descriptions represent values that you must supply. 

[ ] Square brackets enclose optional itons in formats and command 
descriptions. In sample Pascal statenents, square brackets 
assume their Pascal meanings. 
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{ } Braces enclose a list from which you must choose an item in 
formats and command descriptions. In sample Pascal 
statements, braces assume their Pascal meanings. 

CTRL/Z The notation CERL/ followed by the name of a key indicates a 
control character sequence. You should hold down the <CIMi> 
key while typing the character. 

Change Bars in This Revision 

This manual is a revision of 003245 Revision 00. This revision for SR8 
includes new routines and technical changes. These additions and changes are 
indicated by a vertical bar in the margin of a page, i^pendices B, C, and D 
present insert files for Pascal, C, and FORTRAN respectively; these 
appendices do not show any change bars. 

Problems . Questions , and Suggestions 

We appreciate comments from the people who use our syston. In order to make 
it easy for you to communicate with us, we provide the User Change Request 
(UCR) system for software- related comments, and the Reader's Response form 
for documentation comments. By using these formal channels you itake it easy 
for us to respond to your comments. 

You can get more information about how to submit a UCR by consulting the 
DOMAIN System Command Reference Manual . Refer to the CPUCR (Create User 
Change Request) command. You can also get more information by l^ing: 

$HELP CBDCR <RETURN> 

For documentation comments, a Reader's Response form is located at the back 
of each manual. 



SUMMARY OF TEX3iNICAL CHANGES 



The Programmer's Guide to DOMAIN Graphics Primitives > Revision 01 r includes 
new routines as well as changes and additions to existing routines. 

The following new routines are included in this manual: 

• External storage of bitmaps 

New routine opens a file of external storage of a bitmap 

gpr_$open_bi™ap_file 

• New attribute operations 

New routines for fill patterns, background of tile 
fill patterns, and line patterns: 

gpr_$set_fill_background_value 
gpr_$inq_fill_backgrdund_value 

gpr_$set_fill_patrern 
gpil_$inq_fill_pattern 

gpr_$set_line_pa'rtern 
gpr_$inq_line_patrern 

• New text operations 

New routines for setting the direction for writing text, 
creating a modifiable copy of a font, for setting 
character width, horizantal spacing, and space size: 

GPR_$SET_'IEXT_PA'IH 
GPR_$INQ_'IEXT_PA1H 

GPR_$REPLICATE_FONT 

GPR_$SET_CEJARACTER_WIDTH 
GPR_$INQ_CHARACTEIl_WIIXni 

GPR_$SET_HORIZCm'AL_SPACING 
GPR_$INQ_HORIZGNTAL_SPACING 

GPR_$SET_SPACE_SIZE 
GPR_$INa_SPACE_SIZE 

GPR_$SET_TEXT_PA1H 
GPIl_$INQ_TEXT_PAaH 
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GPR_$REPLICATE_PONT 

• Line drawing operations 

New routines for arcs, circles, boxes, and splines: 

GPR_$ARC_3P 

GPR_$CIRCLE 

GPR_$DRAW_BOX 

GPR_$SPLINE_CUBIC_P 

GPR_$SPLINE_CUBIC_X 

GPR_$SPLINE_CUBIC_Y 

• Filling operations 

New routine for drawing and filling circles: 

GPR_$CIRCLE _FILLED 

Throughout the manual, change bars in the itargin of the page indicate 
changes and additions. 
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CHAPTER 1 



INTRODUCTION TO GRAFHICS PRIMITIVES 



Tliis chapter briefly describes the uses and characteristics of the graphics 
priiritives routines (GPR) . Ihe graphics primitives library is built into 
your DOMAIN system. The routines (priiritives) that irake up the library let 
you manipulate the least divisible graphic elements to develop high-speed 
grajiiics operations. These elements include lines and polylines, text fonts 
and values, pixel values, and displ^ types. 

The DOMAIN system also has an optional Gore gr allies package. The Gore 
graj^iics package provides a high-level gra^iics environment in which to 
build portable grajiiics application systors. For a detailed description of 
Gore grajiiics, see the Programmer's Guide to Apollo Core Graphics . 



1.1 USES OF GRAPHICS PRIMITIVES 

The graj^ics primitives include the following capabilities: 

• Drawing lines, circles, and rectangles 

• Acquiring text fonts and manipulating text 

• Manipulating graphics with bit block transfers 

• Filling polygon areas 

• Accommodating input operations 

• Setting attributes 

• Enabling direct graphics operations 

• Imaging with an extended color range 

• Storing bitmaps externally 
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The GPR package uses the following coirponents of the DOMAIN s^steir. 

• A display, 1024x800, 800x1024, or 1024x1024 visible pixels 

• Display irarory, 1024x1024 pixels, or 1024x2048 pixels 

• Any portion of progrctp irannory 

• A set of graphics primitive routines (all begin with "GPR") 

• Optionally, the Displ^ Manager 

1.2 OiARACTERISTIGS OF GRAPHICS PRIMITWES 



Grapiiics priiritives are device dependent with respect to the display. 
However, they are independent of the various display environrents. The 
operating systeir provides two other sets of calls to iranipulate the display: 

Display Manager interface — These program? calls (which begin with PAD) 
allcw you to manipulate pads and frames to display text. You cannot 
manipulate gr allies using these calls. 

Displ^ driver interface — The Displ^ Manager normally controls the 
DOMAIN display. All program requests to read or write the display are 
directed to the Display Manager, which in turn calls the displ^ driver 
to perform screen operations for monochromatic displays. Most of the 
display driver {SfD) calls duplicate functions new provided ty the 
grapiiic primitives package. 

For a description of the calls to the Displ^ Manager interface and the 
display driver interface see the DOMAIN System Programmer's Reference 

GPR routines are independent of the display environments in two w^s. First, 
you can rin a program which includes GPR routines on any of the di spicks 
without modi^ing the prograr. 

Second, grajtiics primitives routines can issue calls to either the Display 
Manager or the displ^ driver. Therefore, if you use the grajdiics primitives 
routines, you can easily change program execution from one displ^ mode to 
another ty changing one option in the initialization routine GPR^$INIT. 
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CHAPTER 2 



DISELAy EN7IRCNMENTS 



This chapter describes the display configurations, fonrats, and irodes within 
which the grajAiics routines can operate. 

2.1 DISELAX- (DNFIGURATIONS 

All DOMAIN displ^s are bit-irapped raster-scan devices. Each node has one of 
three types of DOMAIN displ^s: 

• color 

• ironochraratic portrait (vertical) 

• ironochraratic landscape (horizontal) 



2.1.1 Monochroir a ti c Di splays 

Monochraratic displ^s are either black and white or black and green. The 
ironochraratic displ^ irenpory is 1024 pixels wide and 1024 pixels high. There 
are two different ironochraratic display devices: portrait and landscape. Oi 
the ironochraratic portrait display, the left-irost 800x1024 pixels are 
visible. On the ironochraratic landscape display, the top 1024x800 pixels are 
visible. Figure 2-1 shows the ironochraratic displ^ configurations. 
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Figure 2-1. Displ^^ MOTory Configurations: Monochroratic Displ^s 



2.1.2 Color Displays 

The color displ^ has two types of format: interactive and iiraging. The 
interactive formats support all GPR operations. The imaging formats support 
limited GHR operations, but provide the abilil^ to displ^ more colors. In 
imaging format, images are displayed with more bits per pixel than they are 
in interactive formats. This is useful for color correction in true-color 
imaging. 



2.1.3 Hardware Configurations for Color Display s 

Color displays have either a two- or three-board hardware configuration. For 
either configuration, progrars can change the display between the two types 
of formats. Both types of format are available with both hardware 
oonfiguratdons, as shown in Tables 2-1 and 2-2. This means that either 
configuration provides both interactive processing and more extensive color 
display. 

Table 2-1. TVo-Board Configuration for Color Displ^ 



Fonrat 


Pixel Diirensions 


4-bit interactive (Default) 
8-bit imaging 


Visible Displ^ 


Hidden Display 


Number of Colors 


1024 X 1024 
1024 X 1024 


1024 X 1024 
none 


16 1 
256 
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Table 2-2. Three-Board Configuration for Color Displ^ 



Format 


Pixel Diirensions 


8-bit interactive (Default) 
24-bit iiraging 


Visible Display 


Hidden Display 


Nunpber of Colors 


1024 X 1024 
512 X 512 


1024 X 1024 
512 X 512 


256 
16 million 



T wo-Boa r d C O nf i gucation 

The interactive 4-bit pixel fonrat is the default for a two-board 
configuration. This ireans that 4 bits are used to assign a pixel value 
(color irap index) to each pixel. This fonrat allows sixteen different 
colors to appear on the screen at one tiire. The pixels are arranged 1024 
X 1024 in visible display irorory and 1024 x 1024 in hidden display. 
Interactive fonrats support all GER operations. 

Optionally, software can change a two-board configuration to an 8-bit 
iiraging fonrat, with 8 bits used to assign a pixel value (color irap index) 
to each pixel. This fonrat allcws 256 colors to appear on the screen at 
one tiire, but requires only two boards. The pixels are arranged 1024 x 
1024 in the visible displ^. There is no hidden display. Braging formats 
support only limited GPR operations. 

Three-Board C onf i g u ration 

The interactive 8-bit pixel format is the default for a three-board 
configuration. This means that 8 bits are used to assign a pixel value 
(color map index) to each pixel. This format allows 256 different colors 
to appear on the screen at one time. The pixels are arranged 1024 x 1024 
in visible display metrory, and 1024 x 1024 in hidden display. Interactive 
formats support all GER operations. 

The 8-bit interactive format is compatible with the 4-bit interactive 
format. For example, the Display Manager uses 4-bit planes, but runs on a 
configuration using 8-bit planes. In general, the operations performed in 
an 4-bit format can be performed in 8-bit format. 

Optionally, software can change a three-board configuration to a 24-bit 
iiraging format. This means that 24 bits are used to assign a pixel value 
(color map index) to each pixel, making it possible to use 16 million 
different colors. The pixels are arranged with 512 x 512 in visible 
displ^ and 512 x 512 in hidden display. Imaging formats support only 
limited GPR operations. 

Figure 2-2 and Figure 2-3 show the color display formats available for 
two-board and three-board hardware configurations. 
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INTERACTIVE 4.BIT PIXEL FORMAT 

1024 PIXELS 



1024 
PIXELS 



1024 
PIXELS 



VISIBLE 
DISPLAY 



HIDDEN 
DISPLAY 



4 PLANES 



IMAGING 8-BIT PIXEL FORMAT 

1024 PIXELS 



1024 
PIXELS 



VISIBLE 
DISPLAY 



T 



NO 

HIDDEN 

DISPLAY 



8 PLANES 



Figure 2-2. Color Display MOTory Ponrats: Two-Board Configuration 
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INTERACTIVE 8-BIT PIXEL FORMAT 



IMAGING 24-BIT PIXEL FORMAT 



1024 PIXELS 



LS 



LS 



VISIBLE 
DISPLAY 



HIDDEN 
DISPLAY 



8 PLANES 





512 PIXELS 


512 


VISIBLE 


PIXELS 


DISPLAY 


512 


HIDDEN 


PIXELS 


DISPLAY 




1 



24 PLANES 



Figure 2-3. Color Displ^ Merrory Ponrats: Three-Board Configuration 
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2.2 DISHiAY MDDES 



A graphics prograrr can run in one of four modes: 

• Borrcw-displ^ iP0c3e: on the full screen, which is tenf^porarily 
borrowed f rcn^ the Display Manager. This irode has the option not to 
clear the screen. 

• Direct Mode: within a window, which is acquired frar the Display 
Manager for a period of tiire. 

• Fraire Mode: within a fraire of a Display Manager pad. 

• No-Displ^ Mode: without a display, using only bitiraps allocated 
in irain irorory. 

Progrsn's select a displ^ irode when they initiate a grajiiics session (with 
GPIl_$INIT) . Most of the graphics routines can operate within an/ of these 
irodes; sore routines do not operate in fraire irode. Draging fonrats require 
bor row-display irode. 

2.2.1 Borrow^ Pi splay M ode 

In borrcw-display mode, the program borrows the full screen and the 
keyboard from the Displ^ Manager and uses the displ^ driver directly 
through GFR software. All Display Manager windows disappear from the 
screen. The Display Manager continues to run during this time. However, 
it does not write the output of any other processes to the screen or read 
any keyboard input until the borrowing program returns the display. Input 
typed ahead into input pads ma^ be read while the display is borrowed. 
Borrcw-display mode is useful for programs that require exclusive use of 
the entire screen. 

An option in borrcw-display mode allows you to allocate a bitmap in displ^ 
memory without setting all the pixels to zero. !Ihis is useful for copying 
what is on the screen into a file to save for later display or printing. 



2.2.2 Dir e ct M ode 

Direct mode is similar to borrcw-display mode, but the program borrows a 
window frop the Display Manager instead of borrowing the entire display. 
Illie Displ^ Manager relinquishes control of the window in which the program 
is executing, but continues to run, writing output and processing keyboard 
input for other windows on the screen. Direct mode offers a graphics 
application the performance and unrestricted use of displ^ capabilities 
found in borrow-displ^ mode and, in addition, permits the application to 
coexist with other activities on the screen. Direct mode should be the 
preferred mode for most interactive graphics applications. 
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Chapter 8 describes how prograrrs perfonr graphics input and output in 
direct irode. 



2.2.3 Fraire Mode 

Mternately, a grap^iics program that executes within a frame of a Displ^ 
Manager pad calls the Displ^ Manager, which interacts with the display 
driver. A gra^iics program executes more slcwly in frame mode than in 
bor row-display mode; however, frame mode offers some additional Display 
Manager features: 

• A frame provides a "virtual dispL^" that can be larger than the 
window, allowing the user to scroll the window over the frame. 

• Frame mode irakes it easier to perform ordinary stream I/O to input 
and transcript pads 

• In frame mode, the Displ^ Manager will reproduce the image when 
necessary. 

• The program can leave the image in the pad upon exit so that users 
can view it at some later time. 



Frame mode currently places some restrictions on the GPR operations that 
are allowed. Chapter 11 describes the individual routines, including their 
restrictions. One restriction is described below. 



Implementation Restrictions on Color/Intensity Values in Frame Mode 

Currently, the Display Manager does not store a bitirap when a program 
operates in frame mode. Therefore, a program using frame mode cannot call 
gra^iics routines which depend on particular pixel values of the current 
bitmap. These routines include pixel read and write operations, BLTs that 
use source data f roir the frame, and GPE^$IN2_BITMAP_K)INTER. 

2.2.4 Mo-Di spla y Mo de 

When the program selects no-display at initialization, the GPR 
initialization routine allocates a bitmap from main memory. The program 
can then use GPR routines to perform graphic operations to the bitarap, 
fcypassing any screen displ^ entirely. implications can use no^-display 
icode to create a main memory bitirap, then call graphics map file routines 
to make a file, or send the bitmap to a peripheral device, such as a 
printer. 
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2.3 USING OOLOR DISPLAY FORMATS 



Interactive displ^ fonrats fully si^jport all GPR output operations — 
block transfer, area filling, line drawing, text iranipulation. Innaging 
displ^ fonrats support only liirited display operations — displaying (not 
reading) pixel data and changing the color irap (see Chapter 4 for a 
discussion of color iraps). Other functions will return error iressages. 

liraging displ^ formats make it possible to display images with more bits 
per pixel than are available with interactive formats. Additionally, in 
24HDit pixel format, select frame operations (GEEL.$SELECr_aOLOR_ERAME) are 
allowed. These operations are used to look at either half of display 
memory. 

2.3.1 Using Imaging Displ^ Formats 

Switching the display betiveen an interactive format and an imaging format 
causes the hardware to reconfigure the refresh buffer memory and to 
rearrange the bitmap. This means that an intelligible image in one format 
becomes unintelligible in another. 

•Hie imaging formats are supported only in bor row-display mode. To 
change from an interactive to an imaging format, you must be in 
bor row-display mode. 

2.3.2 Routines foe Imaging Pi splay F or mats 

Use the following routines and procedures for imaging display formats. For 
a detailed description of these calls, see Chapter 11 of this manual. 

1. Establish borrow-dispLay mode: 

GEEl_$INIT 

You m^ or m^ not first want to perform some graj^ics operations in 
interactive format. 

2. Set the displ^ to 24-bit pixel format: 

GER_$SET_IMfiGING_FORMAT 

Use the format argument to switch to 8- bit or 24-bit imaging 
format. 

3. To inquire about the format, use: 
GHl_$INQ_IMfiGING_FORMAT 
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4. To establish new values for the color irap, use: 
GEEL.$SET_(DLOR_MAP 

5. To write pixel data to the display, use: 
GH^$WRITE_PIXELS 

6. To return to interactive fonrat, use the following call with the 
interactive arguirent: 

GHl_$SET_IiyiW3ING_F0RMAT 

7. To tenrinate the session and return the displ^ to the Display Manager, 
use: 

GER_$TERMINATE 
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CHAFTER 3 
MEMDRY REPRESENTATION: BITMAPS AND PIXELS 



This chapter describes bitirap structure and pixels in relation to graphic 
storage and representation. The chapter includes discussion of bitiraps in 
displ^ and irain ireirory, bitirap routines, and bitirap attributes. 

A bitirap is a rectangular data structure that stores a graphic image. A 
pixel (picture eleirent) is a discrete point of a grajdiic iirage. Each pixel 
in a displ^ has a corresponding address in a buffer which stores the iirage. 
Thus, pixels provide the ireans of displacing a graphic iirage. This section 
describes bitmap structure and pixels. 



3.1 BITMAP STRUCTURE 



On a bit-irapped displ^, a one-to-one correspondence exists betsveen the 
screen iirage and display irorory. Oi the screen, a rectangular array (a 
raster) of pixels fonrs the visible iirage. In irorory, a bitirap, a 
rectangular data structure, stores the graphic iirage. 

A bitirap is a three-diirensional array of bits, having width, height, and 

depth. On the ironochroratic display, bitirap width and height may vary; the 

depth equals one. On the color display, bitmap width, height, and depth can 
vary. 

Bitmap width and height correspond to image width and height. Bitmap width 
is represented by x-coordinates ranging f rcir zero on the left to a maximum 
defined for the bitmap on the right. Bitmap height is represented by 
y-coordinates ranging from on the top to a maximur defined for the bitmap 
on the bottom (see Figure 3-1) . When a program establishes bitmap size, it 
determines the maximur x- and y-coordinates. For bitmap size limitations, 
see GPIl_$INIT. 

Bitmap depth specifies the number of bits of information associated with each 
pixel. Each one-bit-deep slice of a bitmap is called a plane of the bitmap. 
This slice has the same width and hei^t as the bitmap. 

On the monochromatic display, bitmaps oontiain one plane; the depth of 
displ^ed bitmaps is one bit. On the color display in 4-bit pixel mode, 
bitmaps can contain up to 4 planes; displ^ed bitmaps can be up to 4 bits 
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deep. On the color c3ispl^ in 8-bit pixel irode, bitiraps can contain up to 8 
planes; displayed bitiraps can be tp to 8 bits deep. 

Planes are nurbered f rar zero to the nurber of bit planes in the bitmap irinus 
one. Plane zero holds the least significant bits of the pixels, and the 
hi^est nun['bered bit plane holds the ipost significant bits. 



PORTRAIT 
SCREEN RASTER 



1-PLANE BITMAP 



MULTI-PLANE BITMAP 
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Figure 3-1 . Screen and Bitn[>ap Width and Hei^t 



3.2 PIXELS 



Oi the ironochroratic display, each pixel consists of one bit. 
dispOL^r a bitmap can have irultiple planes. Therefore pixels 
display can consist of a group of bits. 



On the color 
on a color 



The bitmap pixel values are used ty the color irap to generate the visible 

intensity (dark or bri^t) or color of the corresponding screen pixel. X- 

and y-coordinates reference pixel positions on a bitirapped (raster) display 
and in a bitirap. 

The distance between adjacent pixels on a raster display is called a raster 
unit. The coordinate position (0,0) is at the top left corner of the screen, 
the Display Manager frame, or the bitmap. To change the position of the 
origin, use GPIL.$O0ORDINATE_ORIGIN. 
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3.3 BITMAPS IN DISPLAY, MIN MEMDRY, MD EXTERNAL STORAGE 

A bitirap ir^ reside in display irorory, irain ireroryr or external storage. A 
single graphics session (beginning with GPR_$INIT and ending with 
GHR_$TERMINATE) can involve zero, one, or irore bitiraps in display ireirory and 
irultiple bitrraps in irain irarory. A bitmap resides in only one location at 
any tiire. 

A bitnrap in display ireirory is visible on the screen. A bitmap in irain irerory 
irust be copied to display irarory to beoare visible. A bitmap file may be 
opened to create a bitmap and store it on the disk. The bitmap on which a 
program is operating, whether it resides in display or irain memory, is called 
the current bitirap . The first bitirap created in a gr allies session is 
called the initial bitirap . 



3.3.1 B itir a ps in P isplay M orocy 

Most programs that include a bitirap in display irorory can execute in 
borrcw-displ^ irode, direct irode, or frame mode. When a program initializes 
the grajiiics primitives, it may select any of these modes. Programs that use 
the imaging format for color display must be initialized in borrcw-displ^ 
mode. These displ^ modes pertain only to progrars which use the screen for 
display of images. For bitmaps of programs that do not display an image, see 
the section below. 

On a monochroratic display, bitmaps in display morory can contain only one 
plane. The initial maximum bitmap size is the size of the visible 
monochromatic display, 800x1024 pixels for portrait displays, and 1024x800 
for landscape displays. 

For a color displ^ in a 4--bit interactive format, display memory bitmaps 
can contain up to four planes; in 8-bit interactive or imaging formats, they 
can contain up to eight planes. In 24-bit imaging format, they can contain 
up to 24 planes. The initial maximur bitmap size is the size of the visible 
color display: 1024x1024 pixels for 4-bit and 8-bit formats; 512 x 512 for a 
24-bit format. 



3.3.2 Bitmaps in Ma in M eir or y 

If a program selects not to dispL^ an image on the screen, it can manipulate 
the image ty allocating a bitmap in main morory. A program might require 
main memory bitmaps, for example, to operate on a bitmap larger than that 
available in displ^ mennory. 

Main morory bitmaps can contain up to eight planes, arranged 4096x4096 
pixels, regardless of the display in use. However, if a main morory bitmap 
is transferred to display memory, the size of the bitmap transferred is 
restricted according to the display type. 
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3.3.3 Pit prapis i n External StQgage 

The routine GEE^$OPEN_BITMAP_FILE allows you to create or open a file for 
storage of a bitmap on the disk. Hiis ireans that you can c3ef ine a gra^iic 
iirage on a bitarap, store the bitirap in a file, and then access it for display 
at a later tiire. You can treat bitrraps for external storage like any other 
GER bitmap. 

3.3.4 In it ial Bitir a p 

When a program calls GPR_$INIT to initialize the grajiiics package, it selects 
a mode of operation and initial bitmap size. An initial bitDpap is created as 
follows: 

• If the program uses the displ^ and operates in frame mode, the 
initial (and current) bitirap is displayed and is the saire size and 
location as the frame. The grajiiics primitives create the frame with 
the size parameters which the progrsBP specifies. 

• If the program operates in direct or borrcw-displa/ mode, the 
initial (and current) bitarap is also displayed. The program chooses 
the bitmap size, which can be equal to or less than the size of the 
screen. If the bitirap is araller than the screen, it is located in 
the top left-most area of the screen or window. Ihe (0,0) bitmap 
coordinate is in the same position as the (0,0) screen coordinate. 

• If the program does not use the displ^, the graphics primitives 
initialization routine designates an initial bitmap in main memory. 
•This bitmap has the dim'ensions which the program has selected. In 
this case the initial, current bitmap is not displ^ed. 



3.4 KUTINES FOR CREATING, CANCELING, IDENTIFYING BITMAPS 

The following routines include features for creating, deleting, and 
identifying bitiraps: 

• GPR_$INIT — initializes the graphics package and establishes a 
current bitmap either in display marory or main meirory, as specified 
ty the program. 

• GPEl_$TEPMINATE — terminates the graphics package and its bitmaps. 

• GPEI_$ALJjOCATELBITMAP — allocates a bitmap in main merory and returns 
a unique descriptor for the bitirap. 

• GPI^$DEALL0CATELBITMAP — deallocates an allocated bitmap. 
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• GH^$ALLOCATE_BITMAP_NC — allocates a bitirap in irain irorory without 
setting all the pixels in the bitirap to zero, and returns a unique 
descriptor for the bitrrap. 

• GPIl_$ALLOa^TE_HI»LBITMAP — allocates a bitirap in hidden display 
iraorory. 

• GPI^$SET_BITMAP — establishes a specified bitirap, in display iremory 
or main irenrory, as the current bitrrap. 

• GPII_$SET_WINDCIW_ID — establishes the character that identifies the 
current bitirap' s window. 

• GPiE^$INQ_WINDCiW_ID — returns the character that identifies the 
current bitirap' s window. 

• GHL.$INQ_BITMAP — returns the unique descriptor for the current 
bitirap, which is in either displ^ irennory or irain irorory. 

• GEE^$INQ_BITMAP_DIMEMSIONS — returns the size and nurber of planes 
of a bitirap. 

• GEE^$SET_BITMAP_DIMENSIONS — changes the size of a previously 
created bitmap. 

• GPR_$INa_BH_BIT_OFFSET ~ returns the offset of the left edge of the 
bitmap in virtual address space. 

• GPiEl_$OPEN_BITMAP_FlLE — Opens a file for external storage of a 
bitmap. 



3.5 ACCESSING AND MMIHJLATING BITS IN A BITMAP 



As described above, a bitmap is a data structure. When a program allocates a 
bitmap, the graphics package maps this data structure into the virtual 
address space. Ttie program has no control of the location or layout of a 
bitmap in virtual address space. Typically, the bits constituting one bitirap 
scan line (one horizontal line in a single plane) occupy sequential locations 
in the address space. Next, a series of address locations is skipped. Then, 
all the bits of the second scan line are stored, and so on. For a given 
bitmap, the offset in marory from the beginning of one scan line to the next 
rerains constant. 

For multiple-plane bitmaps in main morory, plane 1 starts on the scan line 
iirmediately following the last scan line of plane 0. For bitmaps stored in 
bitmap files, this is not necessarily true. The routine 

GER_$0EEN_BITMAP_FILE returns the offset in marory between planes. IMlike 
main marory bitmaps, displ^ed multiple-plane bitmaps on the color display 
can be accessed only one plane at a time. Programs must call the routine 
GPI^$REMAP_CDLOR_MEMDRY to select the plane to access. 
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To access a bit location in order to clear or set the bit value, a progrsmr 
does not specify bitopap x- and y-coordinates. The program must find the 
location of the bit in the virtual address space to manipulate it. lb find 
bit locations, progrsn^s can use the routine GPR_$INQ_BITMAP_K)INTER. Ihis 
routine returns a pointer to the beginning address of the bitarap's storage, 
as well as the nurber of 16-bit words (the offset) between the beginning of 
storage for each successive scan line. 

If a prograr uses the pointer routine to get the address of display memory 
(ironochromatic and color), it should call the routine 

GEEL.$ENABLE_DIRECT_ACCESS after any calls that change the display and before 
using the pointer returned ty GER^$IlSQ_BITiyi?^_K)INTER. Tliis ensures that any 
pending display hardware operations are complete before the program uses the 
pointer to access displa^^ memory (with the routines GH^$READ_PIXELS and 
GHL.$WRITE_PIXELS) . 

For example, to set a bit to 1 at the bitonap coordinate position x = 64, 
y = 3, you can write a section of a FOKERM program, using the pointer 
statement, as follows: 

INTE]GER*2 X, Y 

INTE]GER*2 BIT_WORD 

INTBGER*4 INDEX 
C 

INTBGER*4 BITMAP_PER, BITMAP_nESCRIPrOR, STATOS 

INTBGER*2 OFFSET 
C 

INTBGER*2 BITMAP 

POINTER /BITMAP_Pnv' BITMAP (0:65535) 



CALL GPEl_$ENABLE_DIRECT_ACCESS( STATUS) 

CALL GPEL.$INQ_BITMAP_POINTER(BITMAP_ra:SCRIFTOR, BITMAP_PER, 
1 OFFSET, STAIUS) 

C 

C To set bit at (x = 64, y = 3) to 1: 

C 

X = 64 

y = 3 

INDEX = (Y * OFFSET) + (X / 16) 

BITJWORD = RSHFr(16#8000, M3D(X, 16)) 

BITMAP (INDEX) = OR(BITMAP (INDEX) , BIT_WORD) 
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3.6 NULTIILE DISPLAYED BITMAPS 



To initialize irore than one winc3ow with graphics priiritives, you can use 
GEEU$INIT irore than once. Tb c3o so, you irust specify fraire or direct c3i splay 
irode in the unit pararreter. Ihe streair identifier for the pad trust be 
different for each window. 

You can draw in all the windows, one at a tiire, ty calling GPEl_$SEr_BITMAP as 
for other drawing operations. The bitrrap descriptor is returned 
autoratically for each initialized window. 

C^lls which access the displ^ bitarap go to the irost recently current screen 
bitmap. This iray be the current screen bitrrap or the screen bitarap that was 
irost recently current if the current bitmap is a irorory bitirap. 

With irultiple displays, input events can core fror several different bitnnaps. 
To identify the source of an input event, the routine GPE^$E7EWT_WAIT or 
GPEL_$CX)ND_WENT_WAIT returns a character. This character is established with 
the routine GPi^$SET_WINDCWLlD, associated with an entered window event. 
That character tells you which window you have just entered. Ihe source of 
input reirains the saire until a left window event is received. 

To establish the identifying character for a window, use the routine 
GPEl_$SET_WINDCW_ID. Tliis routine accepts a character which identifies the 
current screen bitmap or the irost recent screen bitarap. If the current 
bitirap is the screen bitmap, it references that one. If the current bitirap 
is in memory, the routine uses the most recently current bitirap. 

Use GPEI_$SET_WINDCIW_ID to associate a different character with each window. 
A program irust enable entered window events for all windows that will have 
such events. 



3.7 BITMAP ATTRIBUTES 

Each bitmap has a set of attributes which specify the manner in which 
subsequent operations on the bitmap will be performed. For example, 
attributes can specify that only a certain section of the bitmap can be 
manipulated in any subsequent operations or that text written on the bitmap 
will be displayed in specified fonts. 

3.7.1 Peiscciption of At tributes 

For each bitmap, the program must allocate an attribute block and then assign 
it to the bitmap. The attributes in the block specify characteristics of 
graphics operations. 
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Bitirap attributes are the follcwing: clipping window/ coordinate originr draw 
value (pixel value) , fill value (pixel value) , text value, text background 
value, text font, line style, plane irask, and raster operation. These 
attributes are described belcw. 



Cli pping Window 

The clipping window attribute specifies a rectangular section of the bitnnap, 
outside which no pixels can be irodified, as suggested in Figure 3-2. 
(GEI^$SET_CLIPPING_ACriVE does not draw a rectangle, but specifies a 
rectangular area.) After a progrsn^ calls the routine GP!El_$SEaLajIP_WINDCW 
to specify the dipjing window, it ir^ call GHl_$SET_a.IPPING_ACriVE to 
enable the clipping window. 



CLIPPING 
WINDOW 




BITMAP 



Figure 3-2. Clipping Window on a Bitarap 
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CoQcdinate Origin 

The Goorc3inate origin specifies a pair of offset values to add to all 
coordinate positions. These values are subsequently used as input to mover 
line drawing, or bit block transfer (BLT) operations on the current bitirap. 
For example, the coordinate origin affects calls to the routines GEEI_$MCI7E, 
GEEl.$LINE, and GPR_$PIXEl4_BLT. 

Pr aw Va lu e 

The draw pixel value specifies the value to which pixels will be set when 
drawing lines. 

F il l Va lue 

Ihe fill pixel value specifies the value to which pixels will be set when 
filling areas. 

Text Value 

The text pixel value specifies the value to which pixels will be set to 
write text. 

T ex t Ba ckground Va lu e 

The text background pixel specifies the value to which pixels will be set for 
text background. 

T ex t F o nt 

The text font attribute specifies the font in which to display text 
characters in the bitmap. 

i;«ine gtyle 

Ihe line style attribute specifies the style in which to display line 
segments in the bitmap. Line style can be either solid or dashed; if dashed, 
the style scale factor determines the length of the dash. 

Plane Mask 

The plane mask specifies which planes of a bitmap can be modified ty any 
gra^iics operation and which planes are protected from modification. 

Ra ster O peration 

A raster operation specifies the manner in which to combine pixels in one 
plane of source and destination bitmaps to form a new destination bitmap. 
The value of each new destination bit is assigned ty a Boolean function of 
the previous value of each destination bit and the value of the 
corresponding source bit. 
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sixteen raster operations form the set of rules for combining bit values. 
Assigning a raster operation code to a plane of a bitmap alters no values. 
The raster operation code controls how values are logically combined when a 
program subsequently draws or uses a bit block transfer (BLT) to combine two 
bitmaps. (See Chapter 6 for a description of BLTs and their use of raster 
operations.) Table 3-1 lists the op codes and logical functions for the 
sixteen raster operations. Table 3-2 is a truth table of the raster 
operations. 



Table 3-1. Raster Operations and Their Functions 



09. Code 



Logical Function 




1 
2 
3 
4 
5 
6 
7 
8 

9 
10 
11 
12 
13 
14 

15 



Assign zero to all new destination values. 

Assign source AND destination to new destination. 

Assign source AND complonent of destination to new destination. 

Assign all source values to new destination. (Default) 

Assign coirplement of source AND destination to new destination. 

Assign all destination values to new destination. 

Assign source EXCLUSIVE OR destination to new destination. 

Assign source OR destination to new destination. 

Assign complonent of source AND complement of destination to 

new destination. 
Assign source EQUIVALENCE destination to new destination. 
Assign complement of destination to new destination. 
Assign source OR oomplenent of destination to new destination. 
Assign oomplonent of source to new destination. 
Assign complenent of source OR destination to new destination. 
Assign coir^lonent of source OR complement of destination to 

new destination. 
Assign one to all new destination values. 
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Table 3-2. Raster Operations: Truth Table 



SOURCE 

BIT 

VALUE 


DESTINATION 

BIT 

VALUE 


RESULTi^^T BIT VALUES FOR THE FOLLOWING OP OOEES: 
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 




1 
1 



1 

1 


0000000011111111 
0000111100001111 
0011001100110011 
0101010101010101 



3.7.2 Establishing and Changing Attributes 

An attribute block is required to establish bit irap attributes. The initial 
bitnpap has an attribute block associated with it. A prograir irust associate 
an attribute block with each subsequent bitirap, using the following 
procedure:. 

• The progran» first calls GHL.$ALL0CATE_A[raRIBUTE_BL0(3(. This routine 
allocates an attribute block containing a set of default attributes, 
and returns a unique descriptor of the attribute block. 

• Next the prograrn ipust call GFR_$SET_AraRIBUTE_BLOCK with the 
attribute descriptor to associate the attribute block with the 
current bitopap. 

A prograir can associate an attribute block with irore than one bitirap. 
However, if the program changes any attributes in the current bitirap, that 
attribute will be changed on all other bitiraps which have the saire attribute 
block as the current bitirap. 
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The default attribute settings are shewn in Table 3-3. 



Table 3-3. Default Attribute Settings 



Attribute 


£g£ault Setting 


dipping Window 


Saire size as bitirap. If the prograir 
reassigns the attribute block fror one 
bitirap to a sn^aller bitopap, the clipping 
window is autoratically reduced to the new 
bitarap size. 


Clipping Active 


For borrcw-display and fraire iroder false; 
clipping window disabled. For direct irode, 
true; clipping window enabled. 


Coordinate Origin 


(0,0) 


Draw Value 


1 


Fill Value 


1 


Text Value 


1, for borrowed displays, irorory bitiraps, 
and 




display iranager fraires on ironochraratic 
displ^s; 0, for Displ^ Manager frames on 
color displays. 


Text Background Value 


-2 (same as bitarap background, which is 
for borrowed displays and irarory bitmaps, 
and the same as the window background for 
displ^ manager frames) . 


Font 


No default. Program must load and set 
font. 


Line Style 


Solid line. 


Plane Mask 


All planes can be modified. 


Raster Op 


Op = 3, set all destination bit values to 
source bit values. 



To change an individual attribute associated with the current bitarap, the 
program calls one of the attribute-setting routines which acts directly on 
the bitmap. These include, for example, GH^$SEJILCLIP_WINDOW, 

GEE^$SETL.PASTER_OP, and GPR_$SEC_TE1XT_F0NT. When changing attributes, the 
program does not need to change the attribute block. 
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The routines for setting and retrieving attributes are listed belcw: 
S et A ttr i butes 



GEE^$SET_CLIP_WINDOW — changes the cliiping window for the current 
bitirap, 

GHL.$SET_CLIPPING_ACriVE — enables/disables a clipping window for the 
current bitarap. 

GPIL.$SETLCDORDINATE_ORIGIN — establishes x- and y-offsets to add to 
all X- and y-coordinates used as input for these operations: moving 
the current position, line drawing, and block transfers. 

GHL.$SET_DRM_VfiLUE — specifies the color/intensity to use to draw 
lines. 

GH^$SET_FIll4_BACEQSR0UND_VMiUE — specifies the color/ intensity value 
used for drawing the background of tile fills. 

GH^$SET_FILIi_PAlTERN — specifies the fill pattern to use for the 
current bitirap. 

GPIl^$SET_FILL_VALUE — specifies the col or/ intensity to use to fill 
rectangles. 

GH^$SEai_LINESTYLE — specifies the linestyle as solid or dashed. 

GPEl_$SETLLINE_PATTERN — establishes the pattern used in drawing 
lines. 

GHl_$SET_PLANE_MASK — establishes a plane mask that specifies which 
planes to use for subsequent write operations. 

GPEL_$SEi:_RASTEiL_OP — specifies a new raster operation for BLTs and 
lines. 

GPR_$SET_TEXr_BAC3QGRIJND_VALUE — specifies the col or/ intensity to 
use for text background. 

GH^$SET_TEXT_PONT — establishes a new font for subsequent text 
operatJ.ons. 

GHL_$SET_TEXr_VALUE — specifies the col or/ intensity to use for 
writing text. 
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Retrieve Attributes 

• GH^$INQ_CDNSroAlNTS — returns the clipping window and plane irask 
used for the current bitirap, 

• GHL.$INQ_CDORDINATELORIGIN — returns the x- and y-of f sets added to 
all X- and y-coordinates used as input to irove, line drawing, and BLT 
operations on the current bitirap. 

• GHL.$INQ_I»M_VMil)E — returns the color/intensity value used for 
drawing lines. 

• GI^$IlSQ_FIIi_BAaQ3KXfND_VMiUE — returns the col or/ intensity value 
used for drawing the background of tile fills. 

• GHL.$INQ_FILIj_PAraERN — returns the fill pattern in use for the 
current bitirap. 

• GPI^$INQ_FILIi_VMiUE — returns the color/ intensity value used for 
filling rectangles. 

• GHl_$INa_LINE_PATTERN — returns the pattern used in drawing lines. 

• GP5E^$IN;i_LINESTYLE — returns infonration about the current 
linestyle. 

• GPR_$IKQ_KASTEIL.OPS — returns the raster operations in use for the 
current bitirap. 

• GEEl_$INQ_TEXT — returns the text font and text path used for the 
current bitirap. 

• GHL.$INQ_TEXT_OFFSET — returns the x- and y-of f sets f rar the top 
left pixel of a string to the origin of the string's first character. 
This routine also returns the pixel which is the new current position 
after the text is written with GPIL.$TEXr. 

• GPR_$INQ_IEXT_VALIIES — returns the current values of color/intensity 
for text and text background in the current bitirap. 
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CHAPTER 4 

CDLOIV'iNTEINSITy SVECLFlChTlOn 

This chapter describes the oarponents and uses of a color irap. The 
distinctive characteristics of a color irap in interactive and iiraging fonrats 
are presented. 

4.1 THE (DLOR MP: A SET OF CDLOR VALUES 



A color ipap is a set of color values, each representing a visible color or 
intensity. A color value is an encoding of a particular visible 
color/ intensity, based on the RGB (red/green/blue) color irodel. The RGB 
color irodel defines red, green, and blue as primary colors. All other colors 
are carbinations of these priiraries, including the three secondary colors 
(cyan, magenta, and yellow) . 

Graphics programs use a color map to specify color and intensity (gr^-scale) 
values. A program can redefine the color map to assign colors to pixel 
values. To assign different colors to lines or other gr^^ic entities, a 
program must draw thor using different pixel values and then assign the 
appropriate colors to these pixel values. 

Each color value is 24 bits in length and is divided into three 8-bit 
fields. The first field stores the value for the red component of the 
color, the second for the green component, and the third for the blue 
ccxrponent. Each field can have a value in the range 0-255. Ihe 24-bit 
structure allcws for approximately 16 million different color values. 

A field value of zero specifies the absence of the primary color, and a field 
value of 255 specifies full intensity of that primary color. Figure 4-1 
illustrates the structure of a color value. (Color values are declared as 
4-byte integers; the value of the most significant byte is ignored. ) 
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Bit position — > 31 



24 23 



16 15 



8 7 



Ignored 


Red 
Coirponent 


Green 
Carponent 


Blue 
Coirponent 



Figure 4-1. Ctolor Value Structure 



If all fields have equal values, the color value is a shade of gr^, as 
Table 4-1 shows. 



Table 4-1. Exairple of Gr^- Scale Color Values and Visible Intensities 



ijQliiii: :^£aliag 



Visible Ijoloi/Intensity 
Pe pcesented Js^ ±hs £QiQL :^^LLug 



Rlisld £ £lsi^ £lisld 



255 

191 

127 

63 





255 

191 

127 

63 





255 

191 

127 

63 





white 
light gray 
irediur gr^ 
dark gr^ 
black 



4.2 ESTi^BLISHING A GOLOR MAP 



A color irap consists of a set of color irap entries — each is a color value 
associated with an index (see Table 4-3) . Though the association between 
color values and visible colors/intensities cannot be changed, a prograir can 
establish and change the association between indexes and color values ty 
changing the entries in the color irap. In this w^, a progran^ can select the 
set of colors/intensities to constitute a color irap for a particular 
application, and associate ther with particular indexes. See the routines 
GER^$SEIL.a3L0IL.MAP and GHl_$INQ_aDLOR_MAP. 

At initialization of the graphics priiritives package, a default color irap is 
established. The default color iraps for ironochroratic and color displays 
are described belcw. In f raire irode or direct irode, a prograrr cannot modify 
color irap entries and 7-15. 
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4.3 USING A COLOR MAP 



After a color irap is established, a prograrr can use it to specify the 
color/intensity to use for displaying lines, text, text background, 
rectangles, and the full screen, as follows. The prograrr assigns a pixel 
value (color irap index) to the draw value attribute, the text value 
attribute, the text background value attribute, the fill value attribute, 
and/or uses the index to dear the screen. See the description of the 
following routines: 

GER_$SEaLERAWLVALUE 
GFR_$I]SQ_nRiH_VALUE 

gh^$set_text_value 

ger_$set_te}albackground_value 

ghi_$ii;q_text_values 

GER_$SEC_FILIi_VALUE 
GER_$INQ_FILL_VALUE 
GER_$CLEAR 



4.3.1 Color M ap for Mo no c h ro i r atic P isplays 

For a ironochraratic display, the color irap has only two entries. The default 
color irap assigns the color value to color irap index 0, and the color value 
1 to color irap index 1, as Table 4-2 shows. If a program uses the default 
color irap and sets a particular bitirap pixel to 1 (GH^$WHITE), the 
corresponding pixel on the screen appears bright. If it selects 
(GER_$BLACK) , the corresponding pixel would appear dark. 



Table 4-2. Default ODlor Map for Monochroratic Displays 



Color Table 
Index 


Color Value 


Resultant 

Visible Color/Intensity 



1 


(GPK^$BLACK) 
16#FFFFFF (GER_$WHITE) 


black 
white 



4.3.2 Color Map for Color Displays; 4-Bit and 8-Bit Fonrats 

For a color displ^ in the 4-bit pixel fonrat, the color irap has 16 entries, 
with index values 0-15. For a color display in the 8-bit pixel format, the 
color irap has 256 entries, with index values 0-255. In both formats, all 
entries are set to default values at the initialization of the grajAiics 
primitives package. Table 4-3 shews the default color map for color 
displ^s. 
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Table 4-3. Default Color Map for Color Displays 



Color Table 


Color Value 


Resultant 


Index 




Visible , 
Color/Intensity 




R Q B 





1 
2 
3 
4 
5 
6 
7 


(GHl_$BLACK) 
255 (GPR_$RED) 
255 (GER $GPRFN) 
255 (GEEL.$BLUE) 
255 255 (GHl_$C!aN) 
255 255 (GER_$yELlXK) 
255 255 (GER $MAGENTA) 
255 255 255 (GEE^$WHITE) 


black 

red 

green 

blue 

cyan 

yellcw 

iragenta 

v^ite 


8-15 


1 
contain colors used by the Display Manager 

to display windows. 


16-255 


(GER_$BLACK) 


black 



4.3.3 Color Map for Color Displays: 24-Bit Fonrat 

The color map in 24-bit fonrat functions differently frar the color irap for 
other fonrats. In a 4- or 8-bit fonrat, a single color table index is used to 
look up one slot in the table. This slot is 24-bits wide: 8 bits each for 
red, green, and blue. Ihese three taken together describe the color. 

In 24-bit format, the color map for the 24-bit pixel format can be described 
as divided vertically into three parts, each with 8 bits in and 8 bits out. 
Ihree independent color table indices are used, each to look up on 8-bit 
color ccsrponent value. Ihis means that the red piece of the 24-bit value is 
looked up in the red colunrn and is referenced fcy its own index. The green 
piece is looked up in its colurn and referenced ky its own index. The same 
is true for blue. 



The call GER_$SET_aDLOR_MAP uses the same parameters for 24-bit pixels as it 
does for 8-bit pixels. The difference is in the nunnber of colors that can be 
displayed with 24-bit pixels. Ihe primary application for this extended color 
range is color correction for true-color imaging. 



Figures 4-2 and 4-3 illustrate the differences 
maps. 



in the two types of color 
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4-BIT OR 8-BIT FORMAT 



4 BITS or 
8 BITS 



4-BIT or 

8-BIT 

PIXEL VALUES 



DISPLAY MEMORY 



This pixel value is 

used as an index into the color map. 



Index 23 




15 



255 



23 



COLOR MAP 



16,15 



8,7 



COLOR VALUE 



Figure 4-2. 8-Bit Color Map 
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24-BIT IMAGING FORMAT 



24 BITS 




DISPLAY MEMORY 



24-BIT 

PIXEL VALUES 



The three parts of the 
pixel value are used as 
three separate indices 
into three separate color 
maps. 



RED VALUE 





RED GREEN BLUE 

COLOR MAP COLOR MAP COLOR MAP 

Index 7 Index 7 Index 7 



GREEN VALUE 



Green Number 
(8 bits) 




Blue Number 
(8 bits) 



Figure 4-3. 24-Bit Color Map 
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4.3.4 Saving/RestQcing Pixel Values 

In interactive fonratSr a prograir can read the pixel values of each pixel in 
a bitmap or section of a bitirap and store the values in a pixel array. 
Inraging f onrats do not permit read operations. In both interactive and 
imaging f onrats, a program can write the pixel values from a pixel array 
into a bitmap. See the routines GEEL_$READ_PIXEI,S and GPEl_$WRITE_PIXELS. 
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CHAPTER 5 



DRMING AND TEXT OPERATIONS 



This chapter explains the uses of current position and describes drawing, 
filling, and text operations. 



5.1 CURRENT POSITION, CHANGE POSITION 



Drawing and text operations within a bitmap alw^s begin at the "current 
position". Initially, the current position is set to the coordinate position 
at the top left corner of the bitmap (0,0) . To change the current position, 
use the routine GPR_$MOVE. GPR_$MOVE simply changes the current position, it 
does not draw any lines, as Figure 5-1 shows. 



C X contains 400 
C Y contains 400 



CALL GER_$iyDVE (X,y, status) 



CURRENT 
POSITION 








X 


1023 


r ,. 


S 






Y 








799 











X 


1023 


Y 


* ""^ 


-- 


799 







CURRENT 
POSITION 



BITMAP BEFORE CALL 



BITMAP AFTER CALL 



Figure 5-1. Current Position and Changed Current Position 
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5.2 DRMING AND FILLING OEERATIONS 



The graphics primitives package includes routines that draw lines and fill in 
circles, rectangles, triangles, trapezoids, and polygons. The circle, 
rectangle, triangle, and trapezoid routines fUl in a specified circle, 
rectangle, triangle, trapezoid or list of trapezoids. The polygon routines 
define a polygon, draw and fill it immediately, or save its definition for 
later drawing and filling. An arc routine and three spline routines draw 
lines through specified points. 

The draw-line routines draw lines from the current position to the new 
position, and update the current position to the new position. The graphics 
primitives compute the pixel values of pixels along a line as follows. For 
each pixel included in the line, the current draw value combines with the 
pixel's current value, using the raster operations in effect. 

The follcwing FOKCRM example and Figure 5-2 show how the grajiiics primitives 
compute the pixel value as a line is drawn. 

C 

C Set raster op to do exclusive OR on plane zero. 

C 

CMjL, GHL$SET_RASTER_0P (0, 6, STATUS) 
C 

C Set the line drawing value to 1. 
C 

CMJL GHL$SET_DR/*L VALUE (1, STA3US) 
C 

C Draw a line. 
C 

CALL GHL$MDVE (4, 0, STATOS) 

CALL GHL$LINE (7, 11, STATUS) 



Drawing and Text Operations 5-2 



Initial Contents of Bitmap 
(Plane 0) 








1 


2 


X-COORDINATES 
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Final Contents of Bitmap 
(Plane 0) 

X-COORDINATES 
0123456789 10 11 




Y-COORD. 



Figure 5-2. Example of Color Value Conputation for Line Drawing 



The rectangle, triangle, and trapezoid routines fill in a specified 
rectangle, triangle, trapezoid or list of trapezoids. The rectangle routine 
fills a rectangle b^ writing the current fill value into the rectangle 
without regard to its previous contents or the raster operations in effect. 
The triangle, trapezoid, and multitrapezoid routines compute the current fill 
value in the same way as the rectangle routine. 

The polygon routines open and define the boundaries of a polygon, and either 
close and fill the polygon immediately, or close the polygon and return its 
definition to the progrsm for later drawing and filling, ^e routine 
GPIl_$PGCIl_IOLYLINE does not draw a polygon; the routine defines a series of 
line segments for decomposition into trapezoids for filling operations. 

A polygon's boundary consists of one or more closed loops of edges. ^e 
polygon routine GPil_$START_PGCN establishes the starting point for a new 
loop, closing off the old loop if necessary. The polygon routine 
GPIl_$PGaN_K)L!ajI]SIE defines a series of edges in the current loop. 

^e polygon routines GPE^$CLOSE_FILL_IGCN and GER_$CLOSE_RETORli_PGCN close a 
polygon ty decomposing it into trapezoids. The graj^ics primitives define a 
trapezoid as a quadrilateral with two horizontally parallel sides. The 
polygon routines examine the polygon and break it into trapezoids that can be 
filled iirmediately or returned in an array to the program. At a later time, 
the program can reconstruct the polygon ty filling the saved trapezoids with 
the multitrapezoid routine. 

polygon routines define the interior of a polygon to be all points fron 
which a semi- infinite line will cross the polygon boundary an odd number of 
times. The qradiics primitives fill iX)lvaon interiors with 



The 



acaux— X1U.J.J1XUC xxxicr wxxx ^i-u^isis uiic puxy^uii ijutuiuax.y cux uuu iimiujci. v^x 

The gra^iics primitives fill polygon interiors with the current fill 

value regardless of previous contents. 
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The line drawing and rectangle filling routines are shown in the following 
FOPSURP^ examples, 

Uie GPR_$LINE routine draws one line, as shown in Figure 5-3. 



C Current position is (400,400) . 
C X contains 600, 
C Y contains 200. 



CALL GHL.$LINE (X,y, status) 



799 




Figure 5-3. Line Drawing Example 
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The GHl_$POLYLINE routine draws a sequence of connected lines, as Figure 5-4 
shows. 



C Current position is (100,100). 

C XARFAY contains values 100, 400, 400, 600. 

C YARRAY contains values 200, 100, 500, 200. 

C NiOSITIONS = 4. 



CALL GPR_$POLYLINE (XARRAY, Y?\RRAy, NPOSITIONS, STAIUS) 



799 




Figure 5-4. Polyline Drawing Example 
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The GPIL.$M[JLT]IiINE routine draws a sequence of disconnected lines 
(alternating moves and draws) , as Figure 5-5 shows. 



C XARRAY contains values 100, 400, 400, 600, 
C YftRRAY contains values 200, 100, 500, 200. 
C NPOSITIONS =4. 



CALL GPR_$M[JLTILINE (XARRAY, YARRAY, NPOSITIONS, STATUS) 




Figure 5-5. Multiline Drawing Example 
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Hie GHL.$RECrANGLE routine fills in a rectangle, as Figure 5-6 shows. 



C The rectangle is specified ty a data item of the type 

C GEEl_$WINDCIW_T. 

C WINDOW contains values 100, 200, 300, 100. 



CALL GPiEl_$RECrANGLE (WINDOW, STimJS) 



1023 



799 




Figure 5-6. Rectangle Fill Operation 



The following routines draw lines and polygons and fill areas. 



Line Draw ing Operations 



• GPiEl_$ARC_3P — draws an arc from the current position, through two 
other points. 

• GPiL.$CIRCLE — draws a circle with a specified radius around a 
specified center point. 

• GHl_$DRM_BOX — draws an unfilled box given two opposing corners. 
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• GPI^$LINE — draws a line fron the current position to the given 
position. The routine then updates the current position to the given 
position. 

• GPR_$MULTILINE — draws a series of disconnected lines. 

• GPi^$POLiaiINE — draws a series of connected lines. 

• GPIL.$SILINELC[BIC_P — draws a parametric cubic spline through the 
control points. 

• GPII_$SHjINELCCBICLX — draws a cubic spline as a function of x 
through the control points. 

• GPR_$SHiINELaBIC_y — draws a cubic spline as a function of y 
through the control points. 



Fill Operations 

• GPEL_$CIRCLE_FIIiLED — draws a solid circle around the center point 
with the given radius. 

• GPIL.$RBCrANGLE — fills a rectangle. 

• GPIL.$TRIANGLE — fills a triangle. 

• GPEL_$TRAEEZOID — draws and fills a trapezoid. 

• GPK_$MULTITRAEEZ0ID — draws and fills a list of trapezoids. 

• GPIl_$START_PGCN — defines the starting position to create a loop of 
edges for a polygon boundary. 

• GH^$PGa^POLYLINE — defines a series of line segments forming part 
of a polygon boundary. 

• GPIL.$CLOSE_FILIt_PGCN — closes and fills the currently open polygon. 

• GH^$CLOSE_REIURli.PGCN — closes the currently open polygon and 
returns the list of trapezoids within its interior. 
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5.3 TEXT OPERATIONS 



Using the graphics package, a program can mix text characters and graphic 
images in a single bitmap in a Displ^ Manager frame, an acquired window, the 
borrowed display, or main memory. The text routines are: 

• GPIl_$LQM)_PONT_FILE — loads a font from a file into the font storage 
area of displ^ memory. A single program may load multiple fonts and 
then set them for use, one at a time. 

GPIl_$UNLOAD_FONT_FILE — unloads a font. 

GPi^$SET_CHAE^CrEILWinra — set the parameter WimH of the specified 
character in the specified font. 

GPR_$INQ_CHARACrEILWinrH ~ returns the width of the specified 
character in the specified font. 

GPIU$SET_HORIZ(»ITAL_SPACING — sets the parameter for the width of 
spacing bet^^een displayed characters for the specified font. 

GP!l_$INQ_HORIzaqTAL_SPACING — returns the parameter for the width of 
spacing between displayed characters for the specified font. 

GPIl_$INQ_SPACE_SIZE — returns the width of the space to be displayed 
when a character requested is not in the specified font. 

GPIl_$REPLICATELFONT — Creates and loads a modifiable copy of a 
font. 

GH^$SET_SPACE_SIZE — specifies the width of the space to be 
displayed when a character requested is not in the specified font. 

GPR_$SET_TEXT_PONT — selects a loaded font for use in subsequent 
text operations. 

GPIi_$INQ_TEXT — returns the descriptor of the currently set text 
font. 

GPIL.$SET_TEXr_PA'IH — specifies the direction in which a line of text 
is written. 

GPR_$I1SQ_TEXT_PATH — returns the direction for writing a line of 
text. 

GPi^$SET_TEXT_VALUE — specifies the pixel value to use for writing 
text. 

GPR_$SET_TEXIL.BACH3R0UND_VALUE — specifies the pixel value to use 
for text background. 
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• GP!El_$INQ_TEDaLVMiUES — returns the text and text background pixel 
values. 

• GEE^$TEXT — writes text in the current bitanap, beginning at the 
current position and proceeding in the direction specified ty the 
most recent use of GPIi_$SETjrEXr_PAlH. 

• GPI^$INQ_TE2a?_EXTENT — returns the width and height, in pixels, of 
the area a text string would span if it were written with GEE^$TEXT. 

• GPIl_$INQ_TEXT_OFFSET -- returns the x- and y-of f sets f ran the top 
left pixel of a string to be written ty GPEi_$TEXr to the origin of 
its first character. This routine also returns the x~ or y-of f set to 
the pixel which is the new current position after the GPE^$TEXT 
call, lliis is the y-of f set when the text path is vertical. 
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CHAPTER 6 

GRAH3IC BLOCK TRMSFERS: BLTs 

"This chapter describes three types of bit block transfers (BLTs) and their 
uses. The differences between calls to the gr allies priiritives BLTs and 
display driver BLTis are also presented. 

6.1 FUNCTION OF BLTs 



A progrsPT can move a rectangular section (a window) of a bitirap f rar one 
location in irain irorory to another, one location in displ^ iresnory to 
another, or back and forth between locations in display and irain irorory. The 
displ^ hardware and graphics priiritives software iirplenrent these ircves with 
bit block transfers (BLTs). 

A prograrr can use the BLT, for exairple, if it has iranipulated bitiraps in irain 
irerory and needs to copy them to display iremory. Or a program mi^t 
establish a bitmap with a halftone pattern and then use a BLT to combine the 
halftone bitmap with an image drawn on another bitmap, to give the image a 
shading effect. 

6.1.1 Bit BLTs, Pixel BLTs, and Additive BLTs 

T3ie three types of gra^iics primitives BLT operations are as follows. 

• A bit BLT is an operation that moves a single plane of the source 
bitmap to a single plane of the destination bitmap. 

• A pixel BLT is an operation that moves all planes of the source 
bitmap to the corresponding planes of the destination bitmap. 

• An additive BLT is an operation that moves a single plane of the 
source bitmap to all unmasked planes of the destination bitmap. A 
program can, for example, store character fonts and graphic templates 
in a compact, monochromatic form in a single plane of a bitmap. 
Later, the program can select various colors for various instances of 
the torplate fcy performing additive BLTs on the single-plane template 
bitmap and the appropriately colored multi-plane bitmap. 
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6.1.2 Using a Plane Mask With a PLT 

A prograrr can irask planes of a bitirap to establish the following : 

• source planes of a pixel BLT operation 

• destination planes of a pixel BLT operation 

• destination planes of an additive BLT operation 

For plane masking procedures, see the routine GPH_$SETL_ILME_MASK. 

6.1.3 Usin g li st e r Creations W ith a B LT 

When a prograrr invokes a BLT with the default raster operation, the BLT ircves 
the rectangle and retains all bit values. When the prograrr uses a BLT with 
any other raster operation, the BLT ccxpbines two rectangles and assigns the 
resultant bit values according to the raster operation of the destination 
bitmap. 

6.1.4 BLTs for Graphics Priiritives and for the Display Driver 

Table 6-1 shews the differences between calls to the BLTs for grajiiics 
primitives and for the displ^ driver. For additional information about BLTs 
for the displ^ driver see the DOMAIN Systar Programper's Reference . 
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Table 6-1. Characteristics of Bit Block Transfers 



Oal Is to BLTs 


For Graphics Prirritives 


For the Display Driver 


Source and destination bitaraps can 
be rectangles of different sizes. 


Source and destimtion bitiraps irust 
be oonfonring rectangles. 


Starting coordinate position (origin) 
and hei^t and width define a source 
rectangle (window) . Source and 
destination rectangles 
can have different origins.* 


Start and end positions define 
both the source and destination 
arrays. 


The origin of a bitirap is alwa^^-s 
at the top left corner. 


The origin of the bitirap 
can be any corner. 


BLTs can rrove rectangles between 
displ^ and Fain irarory. 


BLTs can irove arr^s only f rar one 
area of display ire^ory to another. 


*See Figure 6-1. 
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Figure 6-1. Infonration Required for Graphics BLT 
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6.2 THE BLT ROUTINES 



^e gr allies BLT routines are as follows : 

• GP!R_$PIXEIt_BLT — performs pixel block transfers f rar arr/ bitirap to 
the current bitarap. 

• GPR_$BIT_BLT — perf onrs a bit block transfer f rar a single plane of 
any bitarap to a single plane of the current bitmap. 

• GHL.$ADDIT]yE_BLT — adds a single plane of any bitirap to all 
unmasked planes of the current bitmap. 



6.2.1 Example of a BLT Operation 

In a BLT operation, bits are transferred only on the rectangular area in 
which the source bitmap, source window, and destination clipping window 
intersect (see Figure 6-2) , Nothing is transferred outside the bounds of the 
bitmap. For example, if the clipping window of the current bitmap (the 
destination bitarap) excludes part of the destination rectangle that would 
otherwise receive pixels, the size of the actual rectangle moved will be 
smaller than the source window. Similarly, if the source window overflows 
the boundaries of the source bitmap, the size of the actual rectangle moved 
will be anraller than the source window. 



Graphic Block Transfers: BLTs 6-4 



SOURCE BITMAP 



DESTINATION BITMAP 



SOURCE 
WINDOW 
WIDTH 

SOURCE 
WINDOW 
ORIGIN 



SOURCE 
WINDOW 
HEIGHT 

SOURCE 

WINDOW 




DESTINATION 
ORIGIN 



RECTANGLE 
MOVED AS 
RESULT OF 
THEBLT 




RECTANGLE TO BE 
MOVED BY 
THE BLT 



CLIPPING 

WINDOW 

OF DESTINATION 

(CURRENT) 

BITMAP 



OUTLINE OF 
SOURCE WINDOW 
SUPERIMPOSED ON 
DESTINATION. ONLY 
SHADED RECTANGLE 
IS ACTUALLY MOVED. 



Figure 6-2. BLT ExairpLe: Intersection of Source Bitrrap, 
Source Window r Destination Clipping Window 
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6.2.2 Exairple of a BLT With a Raster Operation 

Figure 6-3 shows a sourcje bitonap in irain iraorory, a destination bitmap in 
displ^ irororyr and the bitjrap created b/ using a BLT with raster operation 
1, the logical "and" function. The figure shows bits as black, and 1 bits 
as white. 






Figure 6-3. Exairple of BLT With Raster Op Code = 1 (Logical "and") 
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CHAETER 7 
CURSOR ODNTRCL MD INPUT OPERATIONS 



Ihis chapter describes cursor control and input operations. The input 

routines synchronize program execution around input events. These events 

include keystroke, mouse or puck buttons, locator and locator stop from 
mouse or touchpad, and window transition. 

7.1 USING CURSOR OONTRQL 



The complete set of cursor routines is available in borrcw-display and direct 
mode. In frame mode, the cursor is controlled by the Displ^ Manager and is 
alw^s displ^ed. Therefore, in frame mode, you can change only the cursor's 
position. Cursor routines include the following: 

• GPI^$SET_CURSOI^ACriVE — specifies whether to display the cursor. 
Initially, the cursor is disabled. 

• GP![^$SET_GURSOIl_PATTERN — sets a bitmap pattern as the cursor 
pattern. Ihis bitmap can be a maximum of 16x16 pixels. Ihe initial 
cursor size varies, depending on the standard font the Display 
Manager uses. 

• GPIL_$SET_CURSOIL.B0SITION — sets a position on the screen for display 
of the cursor. The initial cursor position is (0,0). Programs 
running in frame mode can call this routine. 

• GP!E^$SET_CURSOIl_ORIGIN — designates one of the cursor's pixels as 
the cursor origin. Thereafter, when the cursor is moved, the pixel 
designated as the cursor origin moves to the screen coordinate 
designated as the cursor position, as shewn in Figure 7-1. 



7.1.1 I m plementa t ion i ^ strictions on th e Cu rsor 

When the cursor is active, the cursor pattern is stored in display memory. 
Therefore, programs that operate in borrcw-dispLay or direct mode, have the 
potential to interfere with the cursor pattern and/or to cause the cursor to 
interfere with a bitmap pattern. To avoid this problem, disable the cursor 
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before performing output 
cursor could be located. 



procedures to any area of the display in which the 



7.1.2 Display Mode and Cursor Control 



In bor row-display and direct mode, the program has complete control over the 
cursor. In direct mode, the program-defined cursor pattern and origin are in 
effect only within the direct mode window. As the keyboard user moves 
between the direct window and other windows on the screen, the system 
autcanatically changes the cursor pattern. 

If the program executes in frame mode, program control of the cursor is 
limited. The only cursor control routine that operates in frame mode is 
GPR_$SET_ajRSOR_POSITION, and the program can move the cursor with this 
routine only if it lies within the frame when GPR_$SET_ajRSOR_P0SITION is 
called. 



BITMAP CONTAINING 
CURSOR PATTERN 




GIN WILLBE 



SET HERE 



CALL GPR_$SET_ajRSOR_ORIGIN (8,0,SrATOS) 

CALL GPR_$SET_CURSOR_POSITION (400,400, STATUS) 



Figure 7-1. Cursor Origin Example 
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Figure 7-1. Cursor Origin Example (continued) 



7.2 USING INPUT OPERATIONS 



The graphics primitives package includes a set of routines that enable 
graphics programs to accept input from various input devices. The input 
routines synchronize program execution around input events. Input routines 
function in all display modes except GPR_$NO_DISPLAy. 



7.2.1 Event Typ es 

An event occurs when input ia generated in a frame, window, or borrowed 
display. The GPR package supports several classes of event, called event 
types. Programs use an input routine to select the type of event to be 
reported to them; this operation is called enabling an event typ e. The event 
types are the following: 

• Keystroke event — A keystroke event occurs when you type specified 
keyboard characters. Programs can select a subset of keyboard 
characters, called a keyset , to be recognized as keystroke events. 
Except in borrow-display mode, keys that do not belong to the keyset 
are processed normally by the Display Manager. 

• Button event — A button event occurs when you press a button on the 
mouse or bitpad puck. 

• Locator event — A locator event occurs when you move the mouse or 
use the touchpad or bitpad. 

• Locator stop event — A locator stop event occurs when you stop 
moving the mouse or stop using the touchpad or bitpad. 

• Window transition event — Except in borrow-display mode, the cursor 
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may mcve into and out of the window in which GPR input is being 
performed. When the cursor leaves a window used for graj^ics 
display, the input routines report to the program an event of type 
GER_$LEFT_WINDC1W. When the cursor enters the window, the routines 
report an event 1^^ of GH^$ENTERED_WINDCIW. 



Enabled input events are stored in attribute blocks (not with bitmaps) in 
much the same way as attributes are. However, you cannot set and inquire 
about input events in the same way that you can attributes. You use 
GER_$ENABLE_INFUT and GHl_$DISABLE_INPUT instead of GPR_$SET. .. and 
GFFL_$INQ. . . . The effect of this difference is the following. When a program 
changes attribute blocks for a bitmap during a graj^ics session, the input 
events you enabled are lost unless you enable those events for the new 
attribute block. 



7.2.2 Eve nt Re p or ting 

If an event type is enabled, the input routines will report each event of the 
enabled type to the program with a cursor position. This position is 
relative to the upper left corner of the window. 

If the enabled event type is keystroke or button, the input routines will 
return an ASCII character fran the enabled keyset. When defining a keyset 
for a keystroke event, consult the i^stem insert files /SYS/INS/KBD.INS.EAS, 
/SYS/lNS/KBD.INS.FrN and /SYS/INS/KBD. INS. C. These files contain the 
definitions for the non-ASCII keyboard keys in the range 128 through 255. 

The input routines report mouse and bitmap button events as ASCII 
characters. "Down" transitions range fran "a" to "d"; "up" transitions range 
from "A" to "D". The three mouse keys start with (a/A) on the left side. As 
with keystroke events, button events can be selectively enabled fcy speciifying 
a button keyset. 

Locator events merely report the x- and y-coordinates of the locator input. 
If the program has not enabled locator events, the GFR software handles any 
locator data itself by moving the arrow cursor around the window. At the 
next occurrence of an enabled event, the GPR software reports the locator 
final cursor position to the program as well as the enabled event. 

As noted above, enabled input events are stored in attribute blocks (not with 
bitmaps) in much the same w^ as attributes are. When a program allocates 
more than one attribute block, different sets of events are associated with 
each attribute block. The events enabled for a particular bitmap are the 
events stored in the attribute block for that bitmap. You must enable the 
desired events for each window. 

GPIl_$ENABLE_INHJT and GHl_$DISABLE_INRJT work on the attribute block of the 
following bitmap: the current bitmap if it is a screen bitmap; otherwise, the 
screen bitmap which was most recently current. 
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When you have more than one bitmap displayed, you can determine the source 
of input in either of two w^s: 

-Make certain that you have enabled enter ed-window events for all 
windows. Then rononber which window was the last entered. This 
window is the source of the input event. 

-Use GPR_$INQ_WIND0W_ID after each input event. 

You can assign a distinct character to identify each window. To do this, use 
GF!Ei_$SET_WINDCW_ID. This allows you to determine which window was entered 
when an input event occurs of the enter ed-window type. 

7.2.3 Input Routines 

The grajiiics primitives provide the following routines to perform input 
operations: 

• GPR_$ENABLE_INRJT — enables events of a specific event type. If the 
event type is keystroke or button, the routine also enables a 
specific keyset to select which keys or buttons will generate input 
events. Programs must call this routine once for each event type to 
be enabled. 

• GPR_$DISABLE_INHJT — disables events for the event type previously 
enabled with GPR_$ENABLE_INHJT. 

• GH^$EVENT_WAIT — suspends program execution until one of the events 
enabled by GER_$ENABLELINHJT occurs. If the event type is keystroke 
or button, this routine waits until a member of the specified keyset 
is input. The information returned includes the type of event that 
occurred, the character (if any) associated with the event, and the 
position at which the event occurred. The position will be relative 
to the upper left corner of the window, or, if the mode is 
borrow^display, the screen. 

• GPR_$O0ND_EVENT_WAIT — Performs the same function as GH^$EVENT_WAIT 
except that if no event has occurred, the routine returns to the 
program immediately with an event type which indicates that no event 
has occurred (GHl_§NO_EVENT) . 

• GHl_$GET_EC — returns the eventcount associated with a graphic input 
event. Programs can use this routine in conjunction with 
GHL.$(XM)_EVEISlT_WArr to wait for a combination of system events as 
well as GPR input events. 

• GPI^$SET_INHJT_SID — establishes a selected stream as the standard 
input stream. The default standard input stream is STE^EAfL$STDIN. 
Programs can only use this call in frame mode. In bor row-display and 
direct modes, input comes directly from the keyboard. 
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• GPII_$SET1_WINDCIW_ID — establishes the character that identifies the 
current bitaiap's window. This character is returned by 
GH^$EVE3SIT_WAIT and GH^$CDND_EVENT_WAIT when they return 
GH^$ENTERED_WINDOW events. The character indicates which window was 
entered. 

• GPI^$INQ_WINDClWLID — returns the character that identifies the 
current bitinap's window. 

The calling sequence for each of the input routines is described with the 
other GPR routines in Chapter 11. 
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CHATTER 8 



DIRECT GRAHilCS IN WINDOWS 



This chapter describes the routines that graphics programs can call to 
perform input and output to windows. A sample program is included to show 
the input and output calls with other GPR routines, 

8.1 USING DIRECT MDDE 



Programs that select direct mode at initialization (with GPR_$INIT) are 
allowed exclusive access to Display Manager windows for graphics operations. 
In this mode, the GPR software autonatically translates and clips to window 
boundaries all grajhics operations, except program access to display memory. 
The window boundary used by the GPR software is the inner boundary of the 
Displaj^ Manager window, which is five pixels aw^ from the window border seen 
on the screen. 

The next sections describe the routines that grajhics programs can call to 
perform input and output to windows. Tiie calling ^ntax for each routine is 
described with the other GPR routines in Chapter 11. 



8.1.1 Direct Graphics Output 

To perform graphics output to a direct window, programs . must acquire 
exclusive access to display operations within the window fcy calling the 
routine GPR_$AGQUIRELDISILAX'. Programs can only acquire the display for a 
limited amount of time; the default time limit is one minute. However, 
programs can modify the tiine limit with the routine GPR_$SETJVGQ_TIME_CUT. 
The maximum amount of time that a display can be acquired is five minutes. 

In direct mode, the program must acquire the display before calling the 
follcwing routines: 

• GHl_$EVE3OT_WAIT and GPR_$a^D_EVENT_WAIT 

• GPI^$LINE, GPR_$POLniIKE, GPIl_$MULTILINE 

• GPEl_$TEXT 
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• GPIL.$PIXEL_BLT, GPI^$ADDITIVELBLT, and GH^$BIT_BLT 

• GPIl_$CLEftR, GHi_$READ_PIXELS, and GH^$WRITE_PIXELS 

• GPR_$RECrAI«3LE, GPI^$TRIMGLE, GPR_$TRAIEZOID, GPR_$]yiULTITRAIEZOID, 
GPEl_$CIRCLE, GPR_$CIRaE_FILLED, GPEl_$DRM_BOX, GPE^$ARQ_3Pr 
GPI^$SPLINE_aBIC_P, GPR_$SPLINE_aBIC_X, and GH^$SPLINE_CUBIC_Y. 



• GPIL.$STAEOT_PGC»f, GPR_$PGCN_POLYLINE, GPlEl_$aiOSE_FILr4_PGCN and 
GHR_$CLOSE_RETORiq_PG(^ 

• GPR_$ALLOC_HDM_BITMAP 

• GPa_$ENABLE_DIRECr_ACCESSr GPR_$WAIT_FRAME, GPR_$SET_GOLOR_MAP and 
GH^$REMAP_00LOR_MEiyDRY 

The program can call the other graphics primitives routines at any time in 
direct mode, including the cursor routines and any of the set and inquire 
routines. In addition, if the bitmap (s) involved in the drawing calls are 
memory bitmaps (as opposed to screen bitmaps) , the display need not be 
acquired. 

GPIl_$A0QUIRELDISHiA5r establishes exclusive access to display operations 
within a window. If the display is already acquired when this call is made, a 
count of calls is incremented so that pairs of acquire/release calls can be 
nested. A graphics program releases an acquired display fcy calling either 
GEIl_$RELEASE_DISELiAY or GPR_$PORCELRELEASE. The first routine releases the 
display only when the value of the internal counter is equal to one; 
otherwise, it decrements the counter. 

If more than one program module has acquired the display, calling 
GPR_$RELEASE_DISHiAy guarantees that the display will not actually be 
released until all the modules have individually "released" it. The routine 
GEI^$PORCE_RELEASE releases the display regardless of whether or not other 
program modules are currently using it. 

In general, a program creates a graphic image in direct mode ty acquiring a 
display, performing some output, and releasing the display before the timeout 
expires. The program repeats this sequence until the session is completed. 

If the program has not released the display when the time-out expires and 
another process (for example, the Display Manager) needs the display, an 
acquire time-out fault (SiyD_$AaQUIRELTIiyEajT) is generated in the user 
process. The acquire time-out fault is a warning fault that the program can 
intercept with a dean-up handler or static fault handler. If the program 
does not release the display within a few seconds of the acquire time-out 
fault, a second fault occurs (with the status code FAULT_$QUIT) and the 
program loses control of the display. 
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8.1.2 Direct Graphics Input 

Programs can also call GPR input routines in direct mode, as well as in frame 
and in borrov^-di splay modes. When performing input in direct mode, the 
program does not need to acquire and release the display explicitly with 
GEE^$AGQUIRELDISELAy and GHl_$RELEASE_DISPLAy. Instead, the program makes 
one call to GPI^$AGQUIRELDISH.Ay. Then, when the program calls the routine 
GPIl_$EVENT_WAIT or GPIL_$(XasiD_EVENT_WAIT, the routine automatically releases 
and reacquires the display. 



8.1.3 Keyboard Acquisition and Release 

When a program acquires a display, it autcmatically acquires control of the 
keyboard from the Display Manager; releasing the display autcmatically 
returns keyboard control to the Display Manager. 

If the program controls both the keyboard and the display, typing CERL/Q will 
cause a process fault with status code FAULT_$QUIT. On the first CTRL/Q, no 
further action is taken. If a second CTRL/Q is typed with no intervening 
input, the keyboard is forcibly returned to the Display Manager, a second 
fault occurs, and the program loses the display. 

This CTBIj/Q action occurs regardless of whether or not CTRL/Q is included in 
the keyset specified in the call to GPR_$ENABLE_INHJT. To disable the CTRL/Q 
function, the program must call the display driver interface routine 
SMD_$SET_QUnLCHAR. 



8.1.4 Ob s cure d Wi ndows 

As a result of overall screen activity, such as window push/pop, move/grew, 
and window creation, the window associated with the display to be acquired 
can sometimes be obscured. The routine GEE^$SET_CBSaJRED_OEr allows the 
program to specify the action to be taken when the acquire routine encounters 
an obscured window: 

• Pop the window and acquire the display 

• Suspend display acquisition until the window becomes unobscured 

• Return to the program without acquiring the display 

• Acquire the display even if the window is obscured 

If the prograon chooses to acquire an obscured display, it can use the routine 
GPR_$I1SQ_VIS_LIST to locate any unobscured parts of the window. The GPR 
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software does not autonatically clip drawing operations to the visible parts 
of an obscured window. The program must perform this operation with the 
routine GPII_$SET_CLIP_WINDCIW. 

8.1.5 Image Redisplay 

In direct mode, the use of keyboard actions such as push/pop or CTRL/F can 
require that a program redraw the image displayed in a direct-mode window. 
Graphics programs can refresh an image using one of t^o methods: 

• .The program can request that the Display Manager save the bitmap 

image in the window and restore it when necessary with the routine 
GER_$SET_A[JTQ_REFEIESH. This method reduces performance but is the 
easier of the two methods to use. 

• The program can provide its own procedure to redraw the image based 
on data the program has saved. The program calls 
GEEL_$SET_REFE^ESH_BNTRY to specify the entry point for the procedure. 
The procedure is called fcy the GER software whenever the display is 
reacquired and the Display Manager has indicated that the refresh is 
needed. The display is either reacquired explicitly ty 
GPI^$AOQUIRELDISHiAy or implicitly ty GEEL.$EVENT_WAIT. 

A call to GHl_$SET_AUTO_REFElESH or GPEl_$SET_REFE^ESH_EOT!Ry applies to the 
current bitmap. However, the data from these calls is stored in attribute 
blocks (not with bitmaps) in much the same way as attributes are stored. 
This means that when a program changes attribute blocks for a bitmap during a 
graphics session, the auto refresh and refresh entry procedures are lost 
unless you set them for the new attribute block. 



8.1.6 Program Access to Display Monory 

As in bor row-display mode, programs may access display monory directly, using 
the call GPi^$INQ_BITMAP_POI]SITER. Because the window m^ not always be 
aligned on a word boundary, the program must call the routine 
GPEL_$INQ_B1UBIT_0FFSET to establish the window offset from the nearest word 
boundary. The GPR software cannot clip program access to display memory; the 
program must perform this operation itself using the data returned fcy 
GHl_$INQ_BITMAP_DIMEa^SIONS. 



8.1.7 Hidden Piisplay Memory 

To get access to hidden display memory when you are using direct mode, you 
must acquire the display and use the routine GPR_$ALriOC^TE_HDMJBITMAP. A 
program running in an acquired display has exclusive access to hidden display 
memory. However, when the program releases the window, the contents of 
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hidden displ^ memory are no longer protected from modification fc^ other 
programs. The contents of hidden memory ronain intact only so long as no 
other program intervenes. 

A graphics program can provide its own procedure to reconstruct hidden 
dispL^ memory; the routine GPIL_$SET_REFRESH_ENTRY allows the program to 
specify the entry point of the procedure. When the program reacquires the 
display (either explicitly with GPR_$AGQUIRELDISHiM' or implicitly with 
GPR_$EVEJSIT_WAIT) , GPR software calls the user-written procedure to reload 
hidden display memory, if another program or the Display Manager has used it 
in the meantime. 

If the graj^ics program use GPEi_$SET_REFRESH_ENTRY to specify both a window 
refresh procedure and a hidden display memory refresh procedure, the hidden 
display refresh procedure is called first. 

Any fonts loaded ty a program during execution in an acquired display are 
automatically reloaded when the program reacquires the display. 



8.2 PROGRAM EXAMPLE 

This section contains a Pascal program that uses direct mode to handle input 
from a user. The program expects the user to do the following: 

• Wait until the display is acquired, at which time a cursor appears 

• Type in six characters 

• Operate the touchpad 

At any time, typing the character 'q' exits from the program. 
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PROGRAM DIRECr_EXAMFLE; 

% include '/SYS/INS/BASE. INS. PAS ' ; 
% include '/SYS/INS/GPR. INS. PAS ' ; 

VAR 

event: gpr_$event_t; 

sts: status_$t; 

cur_^sition: gpr_$position_t; 

event_tYpe: gpr_$event_t; 

ch: char; 

i: integer; 

timeout: tiine_$clocK_t; 

disp_l:in_size: gpr_$offset_t; 

init_bitinap: gpr_$bitmap_desc_t; 

unobscured: Boolean; 

fwidth, fhite: integer; 

fname: pa<3_$string_t; 

fnsize: integer; 

fnlen: integer; 

fid: integer; 

start: gpr_$offsetL_t; 

xend: integer; 

BEGIN 

{ initialize specifying direct mode } 

disp_fcirL_size.3L_size := 1024; 
disp_tirL_size.y_size := 1024; 
gpr_$init( gpr_$direct, stream_$stdout, disp_bni_sizer 0, init_bitmap, sts ); 

{ set up text font that will be used in direct window } 

pa(L$inq_f ont ( stream_$stdoutr fwidth, fhite, fname, 80, fnlen, sts ); 
gpr_$loa(L.font_f ile( fname, fnlen, fid, sts ) ; 
gpr_$set_text_f ont ( fid, sts ) ; 

{ set time-out to 5 seconds } 

timeout. low3 2 := 5*250000; 
timeout. hi^6 := 0; 
gpr_$set_acq_time_out (timeout, sts); 

{ set obscured option to pop the window if it is currently obscured } 
gpr_$set_obscure<L.opt ( gpr_$pop_if_obs, sts ); 
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{ turn on auto refresh so that the EM will refresh the screen when needed } 

gpr_$set_auto_refresh( true, sts ); 

{ acquire the display. If the window is obscured, it will be popped because 
of the setting of the obscured option } 

unobscured := gpr_$acquire_display( sts ); 

{ enable keystroke event and characters from to 127 which includes all 
white keys } 

gpr_$enable_input ( gpr_$key stroke, [chr(O) ..chr(127)] , sts ); 
gpr_$set_cursor_active( true, sts ); 

FOR i := 1 TO 6 DO 
BEGIN 

{ call event wait and wait for a keystroke event, char, and cursor pos } 

unobscured := gpr_$event_wait( event, ch, cur_position, sts ); 

{ print char at present cursor position and then move the cursor 
to the next position } 

IF event = gpr_$keystroke THEN 
BEGIN 

IF ch = 'q' THEN RETURN; 

gpr_$set_cursor_active( false, sts ) ; 

gpr_$move{ cur_position.xL-COord, cur_position.y_coord, sts ); 

gpr_$text ( ch, 1 , sts ) ; 

{ determine width of character from font, and move 
the cursor fcy that amount in preparation for the 
next input character } 

gpr_$inq_text_offset( ch, 1, start, xend, sts ); 
cur_position.K_coord := cur_position. K_coord + xend; 
gpr_$set_cursor_jposition( cur_position, sts ) ; 

gpr_$set_cursor_active( true, sts ); 
END; 

END; 

{ disable keystroke event } 

gpr_$disable_input ( gpr_$key stroke, sts ) ; 
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{ enable keystroke event and the letter 'q' } 

gpr_$enable_input ( gpr_$key stroke/ ['q'lr sts ); 
gpr_$set_cursor_active( true, sts ) ; 



{ enable locator events } 
gpr_$enable_input ( gpr_$locatorr I], sts ); 

{ call event wait and wait for locator events. Follow cursor returned 
from event wait using gpr_$set_cursor_position. To quit, type 'q' } 

WHILE TRUE DO 
BEGIN 

unobscured := gpr_$event_wait ( evoit, ch, cur_position, sts ) ; 

IF event = gpr_$locator THEN 

gpr_$set_cursor_position( cur_position, sts ) 

ELSE IF event = gpr_$key stroke THEN EXIT; 
END; 

{ disable events } 

gpr_$disable_inpiit ( gpr_$key stroke, sts ) ; 
gpr_$disable_input ( gpr_$locator, sts ); 

{ terminate direct mode graphics } 
gpr_$terminate ( false, sts ); 



END. 
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CEiAPTER 9 

PROGRAMMING INFORMATION 

This chapter lists insert files, data structures with their argument type, 
and error messages. 

9.1 INSERT FILES 

Programs must include the following file, appropriate to their programming 
language, to use system routines: 

FORIRAN Pascal C 

/SYS/INS/BASE. INS. PIN /SYS/INS/BASE. INS. PAS /SYS/ INS/BASE. INS. C 

To use graphics primitives routines, programs must also include the following 
file, appropriate to their programming language. Ihese files contain 
constant definitions required ky the routines. 

FORTRAN Pascal C 

/SYS/INS/GPR. INS. FTN /SYS/INS/GE5^. INS. PAS /SYS/INS/GPR. INS. C 

9.2 DATA STRUCTURES 



The graphics primitives use many common data structures. These are listed 
with their data types. Ihe data structures and data types are described more 
completely in Qiapter 11 with the routines in which they occur. 

9.2.1 Data S truct ures ; PAS Q ^ a nd C 

The data structures and data types shown belcw are defined in the insert 
files for Pascal and C. 
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Data gtructuce 



D at a T ype 



GHi_$ACCESS_MDDELT 



GHi_$ATIRIBUTE_DESC_T 



one of: 

GH^$CREATE, GH^$UPDATE, 

GEE^$WRITE, GHl_$READONLY 

4-byte integer 



GEEl_$BMF_GROUP_HEADEIl_AEy?AY_T 

array [O..GPR_$MAX_BMF_GRajP] of 
GPIL.$BMF_GPOUP_HEADEIl_T 



GEEl_$BMF_GROUP_HEADER_T 



record of six elements: 



N_SECrS 

PIXEL_SIZE 

MIXX3^TED_SIZE 

BlOTES_PEiL_LINE 

BYrES_PER_SECr 

STORAGELOFFSET 



2-bYte integer, 1..8 
2-byte integer 
2-byte integer 
2-byte integer 
4-byte integer 
4-byte integer 



GER_$BITMAP_DESC_T 

GPR_$GOLOIl_T 

GPR_$a)LOIiVECrOR_T 

GPEl_$O0ORDINATE_AE^RAY_T 

GER_$O0ORDINATE_T 

GPR_$DIRECriON_T 

GPiL.$DISHiAy_a:»^FIG_T 



GPiEl_$DISHiAy_MDDEL.T 



GHL.$ECL.KEY_T 



4-byte integer 

4-byte integer 

array of GPR_$OOLOR_T 

array of GER_$CXX)RDINATE_T 

2-byte positive integer 

one of: 

GPE^$UP, GPR_$DOWN, 

GPE^$LEFr, GPEi_$RIGHT 

one of: 

GPR_$BW_800xl024, 
GPEi_$BW_1024x800, 
GPEl_$00LOR_l 024X1024x4 , 
GPEl_$CDLOIL.1024X1024x8 

one of: 

GPEl_$BORRCW, GPEi_$BORRCWLNC 

GPIl_$FRAME, GPR_$NO_DISPLAY, GH^$DIRECT 

GPEL_$INPUTLEC 
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GPR_$EVENT_T 



one of: 

GPIL.$KEySTROKE, 

GPE^$BUTTONSr 

GPEl_$L0CA1DRr 

GPE^$E1SITERED_WINDC1W, 

GPiEL.$LEfT_WINDOW, 

GHi_$LCKATOR_STOP, 

GP!R_$NQ_EVENT 



GPIL_$HORIZ_SBG_T 

GPR_$KEYSET_T 
GPR_$IMAGn«3_P0PMT_T 

GPE^$LINE_PATTERiq_T 
GPIl_$LINESTYLE_T 

GPR_$MASK_T 
GPR_$(BSajRED_OHLT 



GPR_$OFFSET_T 

GPE^$PIXEL_AE^RAy_T 
GI=R_$PIXEL_VALUE_T 
GPR_$ELANE_T 
GPIl_$POSITION_T 

GPR_$RASTEIl_OP_AE«y\Y_T 
GHl_$RASTER_OP_T 



record of three elonents: 

. (jL_coordJ.f 3?_coor^rr y_coord) : GPEL_$OOORDINATE_T 

set of characters 

one of: 

GHL_$INTERACnVE, 
GPEL_$IMfiGING_JL024xl024x8 , 
GPIl_$IMftGING_512x512x24 

four element array of 2-byte integers 

one of: 

GPIL_$SCLID, GPE^$DOTTED 

set of 0.,7 

one of: 

GPR_$OK_IF_CBS, 

GPI^$ERR_IF_CBS, 

GP!R_$POP_IF_CBS, 

GPR_$BLOCK_IF_CBS 

record of two elements: 

. (x_size, y_size) : 0. .32767 

array of 4-byte integers 

4-byte integer 

2~byte integer 

record of two elements: 

. (K_c»ord, y_ooord) : GPR_$CXX)RDINATE_T 

array [0..7] of GPIi.$RASTER_OP_T 
0..15 
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GPR_$STEy:^fG_T 
GHL.$TRAP_T 

GPR_$TRAP_LIST_T 
GHl_$VERSION_T 

GPE^$WINDCIWLT 



GHl_$WINDCIW_LIST_T 



arr^ of characters 

record of two elements: 
.(top, bot): GEEL_$HORIZ_SBG_T 

. (x_coor^_J., 2L_coorcl_r, y-ooord) : 
GEEl_$COORDINATE_T 

array of GPIl_$TRAP_T 

record of two elements: 

• (inajor_version, ininor_verson) : integer; 

record of two elenents: 
.window_base: GER_$POSITIO]SLT 

. (x_ooord, y_coord) : GPIi_$00ORDINATE_T 
.window_size: GER_$OFFSETL.T 

. (x_size, y_size) : 0.. 32767 

array of GPIl_$WINDCW_T 
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9.2.2 Data Structures: FORTRAN 

The follcwing information on data structures and data types is for use t^ 
P0E2IRM programmers. Constants corresponding to the Pascal enumerated types 
are declared in the FORTRAN insert file. 

GHL.$ACXIESS_|ODELT describes the mode of access to external bitmap objects as 
one of the following: 

GHl_$CREATE, 
GER_$UPDATE, 
GEEl_$WRITE, 
GHi_$READCMiY. 

This is an 1*2 variable. 

GHt_$ATTRIBUTEL_DESQjr describes the unique descriptor of an attribute block. 
This is an 1*2 variable. 

GHL.$BMFjGROUP_JffiAIMUVRRML.T describes the array [O..GPR_$MA}e_BMF_GROUP] of 
GPR_$BMF_GRDUP_HEADEIL.T for group headers of an external bitmap. 

GPfL_$BMFjGROUP_HEADEH_T describes the group headers of the external bitmap as 
a record of six elements. In FORTRAN, use the following equivalences: 

Parameter (regroups =1) 

I *2 headers2 ( 8 , regroups) 

1*4 headers4 ( 4 , a_groups) 

Elquivalence headers2(l,l) , header s4 (1,1) 

INSECTS headers2(l,2) 

PIXEL_SIZE header s2 ( 2 , n) 

ALLOCATED_SIZE headers2 (3 ,n) 

BYTES_PER-LINE header s2 ( 4 , n) 

ByrES_PER-SECP header s4 ( 3 , n) 

STORAGiELOFFSET header s4( 4, n) 

GPH_$BITMAPjaESCLT describes the unique descriptor of a bitmap. This is an 
1*2 variable. 

GPiL_$O0iL0iEt_T describes a color value. This is an 1*2 variable. 

GER_$OQ[/3ELVEC3X)IL.T describes a list of color values. This list contains 
4-byte integers, each designating a color value. Use a declaration like the 
follaving: 
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1*4 GOLORJVECTOR (n) 
C (1) = FIRST_00LOR_VALl)E 
C (2) = SEaM)_(DLOIl_VALUE 



GHU$CXX)RDINiKESJ«RWLT describes a list of either x-coordinates or 
y-coordinates. It cx)ntains 2-byte integers. The following FORTRAN example 
declares a variable of this type. 

1*2 OOORDINATELMyRAY (n) 
C (1) = FIRST_}LCXX)RD 
C (2) = SEGCMI_X_G0ORD 



GPIt>$DIRECriOH_T describes the direction of movement fran one text character 
position to the next in the current bitmap as one of the follcwing: 

GEEL.$UP, 
GEEL.$DC)WN, 
GHL.$LEPr, 
GEEl_$RIGHT 



This is an 1*2 variable. 

GPIi_$DISILA5L-CX)NFIGLT describes the display configuration as one of the 
following: 

GHi.$BW_800xl024, 
GHL.$BW_1024x800, 
GHl_$OOLOIl_l 024X1024x4 , 
GHl_$COLOIl_1024X1024x8 

This is an 1*2 variable. 

GHL-^DISHjMCJOD^T describes the display mode as one of the following: 

GH^$BORRCW, 

GHl_$BORRCW_NC, 

GHl_$FRAME, 

GHl_$NO_DISELAY, 

GHl_$DIRECr 

This is an 1*2 variable. 

GHL.$ECL$KEXjr specifies which event count to obtain as GP!E^$INHJT_EC. This 
is an 1*2 variable. 



Programming Information 9-6 



GPR_$EVEinLT specifies input event types as one of the following: 

GP!El_$KEYSTROKE, 

GH^$LOCATOR, 

GH^$ENTERED_WINDCW, 

GHi_$LEFr_WINDCIW, 

GPI^$LOG^TOI^STOPr 

GEE^$NO_EVENT 

This is an 1*2 variable. 

GHL-$H(BIZ__SBG__T describes a horizontal line segment on the screen. It 
contains three 2-byte integers. The first designates the left x-coordinate, 
the second corresponds to the right x-coordinatef and the third designates 
the y-coordinate. In PORERANf use a declaration like the following: 

1*2 H0RIZaQTAE4_SBG]yENT (3) 
C (1) = LEPr_}L_G0ORD 
C (2) = RIGHT_X_G0ORD 
C (3) = Y_CDORD 

GHi.$IMM5ING_P0RMA!lLT specifies pixel and bit values with one of the 
following: 

GH^$INTERACriVE, 

GHl_$I]yifiGING_J024xl024x8, 

GER^$IMAGING„512x512x24 

ihis is an 1*2 variable. 

GHl_$KEYSEILT describes a set of characters associated with the graphics 
input event types GPR_$KEYSTROKE and GPR_$BUTTONS. For a procedure to use in 
building a set of characters, see the routine GHL.$ENABLE_INHJT in Chapter 11 
of this manual. 

GHL.$LINSJPATTERIL.T specifies the bit pattern for drawing lines. This is 
four-element array of 1*2 variables. The pattern bits are used in the 
following order: most significant bit of the first array elanent to least 
significant bit of the last array element. 

GH^$LINESTXLBjr specifies a line as one of two types: 

GHl_$Sa.ID, 
GHL.$DOTOED 

This is an 1*2 variable. 

GHi_$MASFLT describes a set of planes of a bitmap. The bit corresponding to 
plane zero is the Icw^order bit of the word. If a bit of the mask is on, the 
corresponding plane is active. This is an 1*2 variable. 
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GHt.$CBSC[JRED_OFr_T specifies the action for aoqui re-display when the winc3ow 
is obscured as one of the following: 

GH^$OIL.IF_CBS, 
GPIl_$ERR_IF_CBS, 
GPR_$POP_IF_CBS, 
GPiEl.$BLOaL_IF_CBS 

This is an 1*2 variable. 

GHl_$OFFSEILT describes the width and height of a bitmap or a rectangular 
section of a bitmap. It contains two 2-byte integers. The first designates 
the width (xL_size) ; the second designates the hei^t (y_size) . In FOBTRM, 
use a declaration like the following: 

1*2 OFFSET (2) 
C (1) = )eSIZE 
C (2) = Y_SIZE 

GHt.$PIXEi:cJ^EaRMLT describes a list of pixel values. It contains 4-byte 
integers, each designating a pixel value. In POKIKAN, use a declaration like 
the follcwing: 

1*4 PIXEIi_ARRAY (n) 
C (1) = FIRST_PIXEL_VMiUE 
C (2) = SEG0ND_PIXEL_V2LUE 



GHl_$PIXEIc_VM:iU5jr indicates the text color/ intensity value. Ihis is a 
4-byte integer. 

GE^$P0SITI01L.T describes an x-, y-coordinate position on the screen, a 
bitmap, or the cursor. It contains two 2-byte integers; the first designates 
the x-coordinate and the second designates the y-coordinate. In FORTRAN, use 
a declaration like the following: 

INTBGER*2 POSITION (2) 
C (1) = X_aX)RD 
C (2) = Y_aX)RD 

GHL_$RASTERjOP__ARRWLT describes a list of raster operation codes. It 
contains 2-byte integers. In FORTRAN, use a declaration like the follcwing: 

INTBGER*2 RASTER_OP_AE^RAy (n) 
C (1) = FIRST_RASTEIL_OP 
C (2) = SEGC»ID_RASTER_OP 
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GHL.$RASTEIl_OPjr specifies the value of the raster operation code. This is 
an 1*2 variable, ranging fran to 15. 

GPIt.$STRINGLT describes a character string for use in GHl_$TEXr calls. In 
FOKIBM, use a declaration like the follcwing: 

CHARACTER STRING (256) 

GH<_$TRAILT describes a trapezoid fc^ specifying its top and bottan segments 
in GPIL.$HORIZ_SEG_T format. GER_$TRAP_T contains six 2--byte integers. In 
FORTRAN, use a declaration like the following: 

INTEGER*2 TRAIEZOID (3,2) 

C (1,1) = TOP_LEPr_X_G0ORD 

C (2,1) = T0P_RIGHT_}L.G0ORD 

C (3,1) = 1DP_Y_G0ORD 

C (1,2) = BOTT0fi_LEFT_5L.OCX)RD 

C (2,2) = BarT0M_RIGHT_X_C0ORD 

C (3,2) = B0TTC»LY_O0ORD 



GHt_$TRAP_JiiaiLT describes a list of trapezoids in GPR_$TRAP_T format. 
FORTRAN, use a declaration like the follcwing: 



In 



] 


[NTliGER*2 TRAFEZOID_LIST (3,2,n) 


c 


drl.l) 


= top_t,f;ft_x (XOrd 


c 


(2,1,1) 


= TOP_RIGHT_X OOORD 


c 


(3,1,1) 


= TOP Y COORD 


c 


(1,2,1) 


= BCi'lOyi LEFT X COORD 


c 


(2,2,1) 


= BOriOM_RIGHT X-COORD 


c 


(3,2,1) 


= Bai'iU^L.Y_C0ORD 


c 


(lrl,2) 


= TOP_T.EFr_K_O0ORD 


c 


(2,1,2) 


= TOP RIGHTJK COORD 


c 


(3,1,2) 


= TOP_Y_G0ORD 


c 


(1,2,2) 


= BanOM_LEFr_}L_C0ORD 


c 


(2,2,2) 


= BOi'iOM RIGHT X COORD 


c 


(3,2,2) 


= Bai'iOM_Y_C0ORD 
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GHl_$VERSI(»i_T describes the version number on the header of an external 
bitmap file. This is a two-element array of two 2--tyte integers: a major 
version number and a minor version number. Currently, both values must be 
1. 

GEH_$WIN1XW__T describes a rectangular window by specifying both its origin 
(top left corner; type: GEEL.$POSITION_T) and its width and height (type: 
GEE^$OFESETLT) . The width and height are pixel counts and include the origin 
pixel. (For example, a window with the origin at (10,20) and offsets (5,7) 
encompasses the pixels in columns 10 through 14 and rows 20 through 26, 
inclusive.) GPiEL_^INIXK_T contains four 2-byte integers. In order, they 
are the start X coordinate, the start Y coordinate, the X size and the Y 
size. In FORTRAN, use a declaration like the following: 

INTE]GER*2 WINDOW (2,2) 
C (1,1) = WINDOW_STi?^T_X 
C (2,1) = WINDOWLSTART_Y 
C (1,2) = WINDOWLOFFSETLX 
C (2,2) = WIN1XIWL0FFSETL.Y 

GEIL$WINDOWLJiISlLT describes a list of windows in GPIi_!^INDOW_T format. In 
FORTRAN, use a declaration like the following: 

INTE)GER*2 WINDOW (2,2, n) 

C (1,1,1) = WINDOWLSTART_X 

C (2,1,1) = WIMX)WLSrART_Y 

C (1,2,1) = WIMXW_OFFSET_X 

C (2,2,1) = WINDOW_OFFSET_Y 

C (1,1,2) = WINDOWLSTART_X 

C (2,1,2) = WINDOWLSTART_Y 

C (1,2,2) = WINDOW_OFFSET_X 

C (2,2,2) = WIMXM_OFESET_Y 
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9.3 ERROR MESSA3ES 



The following are 
primitives package. 



the possible error messages generated fc^ the graphics 



GER^$NOT_INITIALIZ ED 
GHL.$ALREM)y_INITIALIZ ED 
GH^$WR(K3_DISELAY_HZVRrWARE 
GER_$ILLBGMi_POIL.FRAME 
GPIl_$MUST_Ba^CW_DISELAY 

GHl_$NQ_A!ITRIBUTES_DEFINED 

GHL.$NQ_MDRELSPACE 

GER_$DIMENSION_T0O_BIG 

GEE^$DIMENSI0N_1D0_SMMiL 

GHl_$BAD_BITMAP 

GPR_$BAD_MTRIBUTELBIiOCK 

GH^$WIND0W_0UT_OF_B0UNDS 
GER_$S0URCE_0UT_OF_B0UNDS 

GER_$DEST_0UT_OF_BaJNDS 

GEE^$INVM4lD_HiANE 

GER_$CANT_DEALIXXATE 

GER_$CXX)RD_OUT_OF_BaJNDS 

GER_$INVALID_G0LOR_J4AP 

GPIL.$INVALID_RASTER_OP 

GPR_$BITiyiAP_IS_READ_CNLy 

GHI_$INTERNA]l4_ERR0R 

GPEL.$FaSIT_TABLE_KILL 

GPEl_$BAD_roNT_FILE 

GPEi.$INVALID_FONT_ID 

GPEL_$WINDOWLCBSajRED 

GPR_$NOT_nq_DIRECr_MDDE 

GPR_$NOT_Iiq_POLyGCN 

GPEl_$KBD_NOT_AGQ 

GPR_$DISPLA!CNOT_AGQ 

GPR_$ILLBGAL4_PIXEL_VALUE 

GPEi_$ILLBGAL_WHEN_IMAGING 

GPEl_$INVALID_IMAGING_FORMAT 

GPI^$MUST_RELEASE_DISELAy 

GHl_$CANT_MIX_M3DES 

GPR_$NO_INH]T_ENABLED 
GPEl_$DUPLICATELPOINTS 



Primitives are not initialized. 

Primitives are alrea^ initialized. 

The display hardware is wrong. 

Operation is illegal for DM frame. 

you must borrow the display for this 

operation. 

No attributes are defined for the 

bitmap. 

No more bitmap space is available. 

The bitmap dimension is too big. 

The bitmap dimension is too small. 

The bitmap descriptor is incorrect. 

The attribute block descriptor is 

incorrect. 

Window origin is out of bitmap bounds. 

Source window origin is out of 

bitmap bounds. 

Destination window origin is out 

of bitmap bounds. 

The plane number is invalid. 

you cannot deallocate this bitmap. 

Coordinate value is out of bounds. 

The color map is invalid. 

The raster operation value is invalid. 

Bitmap is read-only. 

This is an internal error. 

Font table is full. 

Font file is incorrect. 

Font id is invalid. 

Window is obscured. 

Display is not in direct mode. 

No polygon is being defined. 

Keyboard has not been acquired. 

Display has not been acquired. 

Pixel value range is illegal. 

Call is illegal in imaging format. 

Format is invalid for display hardware. 

you must release the display for this 

operation. 

You cannot mix display modes, for 

example, borrow and direct. 

No input events are enabled. 

Duplicate points are illegal. 
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GH^$ARRAy_NDaL_SORIED Array must be in ascending order. 

GHL.$CHARACrEIL.NOT_ni_FONT Character is not in a font. 

GPR_$ILLBGAL4_FILL_PATrERN Illegal bitmap for a fill pattern. 

GH^$ILLBGAL_FILIt_SCALE Fill pattern scale must be one. 

GH^$INGORRECr_ALIGNiyENT Bitmap layout specifications do 

not satisfy GPR alignment constraints. 
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CHAPTER 10 

PROGRAMS AND TECHNIQUES 

This chapter presents sairple prograrrs and techniques for using gcaptiics 
priiritives. Progrcn-s include a brief Pascal prograir to illustrate a basic 
programriring fonrat. A P0R1RAN prograir illustrates creating a iren-ory bitirap, 
drawing a figure, adding text, and selecting a displ^ irode. Other prograrrs 
and techniques include the following: the use of bit plane irasks; input and 
event wait routines; rubber banding; and display irodes. 



10.1 EXAMHiE HIOGRAM: PASCAL 

The following prograrr draws a three-sided, elongated box. Ihe lines of the 
box are drawn with two line styles — solid and dotted. Input, coirpile, and 
run this short prograir for a deronstration of a few routines. 

progran- testgpr; 

%nolist; 

%include '/sys/ins/base.ins.pas' ; (required insert file} 

%include '/sys/ins/gpr.ins.pas' ; (required insert file} 

%list; 

VAR 

St : status_$t; 

disp_tir_size : gpr_$offset_t; (data structure for size of initial bitirap} 

init_bitirap : gpr_$bitirap_desc_t; (data structure for descriptor of 

initial bitirap} 

attr_desc : gpr_$attribute_desc_t; (data structure for attributes} 

i : integer; (type of value for line drawing} 
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BEGIN 

{Initialization is required. Borrow irode is chosen here for display. } 

disp_tir_size.K_size := 1024; 
disp_tir_size.y_size := 1024; 
gpr_$init (gpr_$bor row , 1 , disp_l3r_size, , ini t_bitirap, st ) ; 

for i:= 100 to 600 do begin 

{Call gpr_§irove to change the current position.} 

gpr_^ove ( i, i, st ) ; 

{Draw lines frcir the current position to the given position.} 

gpr_$line (i+100,i,st) ; 
gpr_$line (i+100, i+lOO^st) ; 

{Change the linestyle fror solid to dotted.} 

gpr_$set__linesty le (gpr_$dotted, 5 , st ) ; 

{Draw dotted lines fror the new current position to the given position. } 

gpr_$line (i, i+100,st) ; 

{Change the line style back to solid. } 

gpr_$set_line style (gpr_$sol id, , st ) ; 
end; 

{End the use of graj^ics priiritives. } 

gpr_$tenrinate (false, st) ; 
END. 
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10.2 E3CAMPLE PROGRAM: PORTOM 



This prograir creates a iren^ory bitrrap, transfers the bitirap to the displ^ 
using a BLT, and adds a caption in the display. The prograrr asks the user 
whether to use a fraire of the Display Manager or to borrcw &ie displ^. The 
prograir uses GHl_$EN/BLE_INHJT. This routine requires a set of characters. 
For a description of the procedure for building a set of characters, 
GER_$ENABLE_INHJT in Chapter 11 of this iranual. 



C 
C 

c 



This prograir irust be coirpiled with the -1*2 option! 

PROGRAM lEK) 
C 

IMELiaT INTBGER*2 (A-Z) 
C 

c 

C Required insert files 

C 

%INCLUDE '/SYS/INS/BASE.INS.PIN' 

%INCLUDE •/SYS/lNS/SMDU.INS.PrN' 

%INaUIS; •/SyS/lNS/ERROR.INS.PrN' 

%INCHJDE '/SYS/lNS/GFR.INS.PrN' 

c 
c 

CHARACTER ANS(3) 

INTBGER*2 NODE, UNIT_OR_PAD, PONT 

INTBGER*2 BSIZE(2), SWIND(2,2), DP0S(2) 

INTBGER*2 B0}UC(4) , B0X_Y(4) , STAR_X(8) , SrAIi_Y(8) 

INTBGER*4 ST, TERM_ST 

INTBGER*4 DISP_KISC, MEM_I»1SC, ATTR_I]ESC 

INTBGER*2 KEY_SET(16) 

INTBGER*2 EJJTfPE, EV_P0S(2) 

CHARACTER EV_CHAR 

LOGICAL UNCBSCDRED 



C 
C 
C 

C 
C 
C 



C 
C 



KEy_SET is a set of all 8-bit characters. 

EATA KEY_SET /16 * 16#FFFF/ 

Describe the figure to be drawn. 

DATABO}C_X 7 200,200, 0, 0/ 

DATA BOX_Y / 0, 200, 200, 0/ 

DATA STAR_X / 200, 0, 100, 200, 0, 200, 100, 

DATA STAR_Y / 100, 200, 0, 200, 100, 0, 200, 



0/ 
0/ 



1010 FORMAT (' Do you want to use a Display Manager fraire?') 
1020 FORMAT (3A1) 

I Ask which w^ to display the result. 
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WRITE (*, 1010) 

READ (*, 1020) ANS 

lOm = GER^$BORRCW 

IF (MS(1) .EQ. •¥•) Wm = GPR_$FRAME 
C 

C Initialize the gr^hics prirritives. 
C 

BSIZE(l) = 800 

BSIZE(2) = 800 

UNIT_aR_PAD = 1 

CALL GER_$INIT(MODE, UNIT_OR_PAD, BSIZE, GHl_$HIGHEST_HiANE, 

* Disp_ra:sc, ST) 

IF (ST .NE. STAIUS_$OK) GOTO 9998 
C 

C Allocate an attribute block. 
C 

CALL GER_$ALLOCATE_AaTEaBUTE_BLOCK(ATTR_DESC, ST) 

IF (ST .NE. STATOS_$OK) GOTO 9998 
C 

C Allocate a ireirory bitarap. 
C 

BSIZE (1) = 201 

BSIZE (2) = 201 

CALL GHl_$ALLOCATE_BITMAP (BSIZE, GH^$HIGHEST_ILANE, im!!UXlSCf 

* mtuxisc, ST) 

IF (ST .NE. STATOS_$OK) GOTO 9998 
C 

C Make it the current bitoap. 
C 

CALL GH^$SET_BITMAP(MEM_EESC, ST) 

IF (ST .NE. STAIUS_$OK) GOTO 9998 
C 

C Draw the figure in it. 
C 

CALL GH^$MD7E(0, 0, ST) 

IF (ST .NE. STA!IUS_$OK) GOTO 9998 

CALL GPIl.$POL^INE(BOX_X, BO}e_Y, 4, ST) 

IF (ST .NE. STA!IUS_$OK) GOTO 9998 

a\LL GPR^$POLYLINE(SrAR_X, SEAR_Y, 8, ST) 

IF (Sr .NE. STAIUS_$OK) GOTO 9998 
C 

C Invert sore pixels in it. 
C 

CALL GPR_$SET_RASTER_OP(0, 10, ST) 

IF (ST .NE. STATOS_$OK) GOTO 9998 

SWIND(1,1) =50 

SWIND(2,1) =50 

£WIND(1,2) = 101 

SWIND(2,2) = 101 

DPOS(l) = 50 

DP0S(2) = 50 

CALL GH^$PIXEIi_BLT(MEM_I:ESC, SWIND, DPOS, ST), 
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IF (ST .ME. STATOS_$OK) GOTO 9998 
C 

C Make the display the current bitirap. 
C 

CMiL GHl_$SET_BITMAP(DISP_nE;SC, ST) 

IF (ST .NE. STAIUS_$OK) GOTO 9998 
C 

C Do the bit block transfer to the dispLcy. 
C 

SWIND(1,1) = 

SWIND(2,1) = 

SWIND(1,2) = 201 

SWIND(2,2) = 201 

DPOS(l) = 300 

DP0S(2) = 300 

CALL GPR_$PIXEIi_BLT(MEM_ffiSC, SWIND, DPOS, ST) 

IF (ST .ME. STATUS_$OK) GOTO 9998 
C 

C Write the caption. 
C 

CALL GH^$LOAD_F0NT_FILE('STD', 3, FONT, ST) 

IF (ST .NE. STATUS_$OK) GOTO 9998 

CALL GH<_$SET_TEXT_FONT(FONT, ST) 

IF (ST .ME. STATUS_$OK) GOTO 9998 

CALL GHl_$iyCVE(375, 550, ST) 

IF (Sr .NE. STAIUS_$OK) GOTO 9998 

CALL GHL.$TEXr(' Widget', 6, ST) 

IF (ST .NE. STA!IUS_$OK) GOTO 9998 
C 

C If display is borrowed, wait for a key to be struck. 
C 

IF (NDEE .B2. GPEL.$BORRCW) THEN 

CALL GER_$ENi^LE_INHJT(GHl_$KEYSTROKE, KEY.SET, ST) 

IF (ST .NE. STATUS_$OK) GOTO 9998 

UNOBSOJRED = GEEl_$EVENT_WAIT(EV_TYPE, E^_CHAR, EV_K)S, ST) 

IF (ST .NE. STATU S_$OK) GOTO 9998 

ENDIF 
C 

C Finish up. 
C 

CALL GER_$TERMINATE(. FALSE. , ST) 

GOTO 9999 
C 

C Report an error. 
C 

9998 CONTINUE 

CALL GHl_$TERMINATE(. FALSE. , TERM_Sr) 

CALL ERROR_$PRINT(ST) 
C 

C Exit. 
C 

9999 ODNTINUE 
END 
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10.3 USING BIT PLANE MASKS 

Masking a plane so that a prograrr cannot write pixel data to it has a variety 
of uses. One use is to irask a bit plane that holds a grid. The grid renrains 
unchanged when it is displayed with other gra0iic iirages. This technique 
requires writing a plane with a grid and then irasking the plane so that other 
data is not written to it. 

Another use of bit plane irasks is illustrated fcy the prograir belcw. "This 
prograrr uses an ei^t-plane refresh buffer to hold two independent iirages. 
The program shews first one iirage and then the other. Ihis is acooirplished 
ty careful loading of the color irap ty placing all the color values 
associated with each iirage into appropriate slots of the bitmap. Ohe prograir 
also demonstrates the use of TIMEL$WAIT to set the interval between the 
display of images. 

program planes_example; 

%insert '/sys/ins/base.ins.pas' ; 
%insert '/sys/ins/gpr . ins. pas ' ; 
%insert '/sys/ins/time. ins. pas ' ; 
const 

one_second = 250000; 

var 

St: status_$t; 
i: integer; 

bitm: gpr_$bitmap_desc_t; 
bitm_size: gpr_$offset_t; 
bitm_hJLplane : gpr_$plane_t; 

plane_mask: gpr_§irasK_t; 
current_value: gpr_$pixel_value_t; 
color_map: gpr_$color_vector_t; 
dim_gr^: gpr_$color_t; 

wait_time: time_$clock_t; 

procedure draw_triangle(x, y: gpr_$coordinate_t) ; 

{ Draw a triangle based at x, y. } 

var 

St: status_$t; 

pi, p2, p3: gpr_$position_t; 
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begin { draw_triangle } 
pl.3L_ooord := x; 
pl.y_cxx)rd := y; 
p2.x_cx)ord := x + 150; 
p2.y_cxx)rd := y + 30; 
p3.x_ooord := X + 30; 
p3.y_coord := y + 150; 
gpr_$triangle(pl, p2, p3, st); 
end; { draw_triangle } 

begin { planes_exairple } 

{ Initialize ty borrowing the display and checking the refresh buffer size,} 

bitar_size. x_size := 1024; 

bitir_size.y_size := 1024; 

bitan_hi_plane := 7; 

gpr_$init(gpr_$borrow, 1, bitar_size, bitir_hi_plane, bitiT/ st); 

gpr_$inq_bitirap_diirensions(bitir, bitrr_size, bitir_hi_plane, st); 

if bitop_hl_plane = 7 then begin { only if an eight-plane systor } 

{ Blank out image while you draw it. } 

for i := to 255 do oolor_jrap[i] := gpr_$black; 
gpr_$set_color_jrap(0, 256, oolor_jrap, st); 

{ First, draw a three-plane iirage of overlapping triangles 
in planes 0-2.} 

plane_jrask := [0, 1, 2]; 

gpr_$set_plane_jrask (pi ane_jrask , st ) ; 

for i := to 7 do begin { 8 colors } 

current_value := i; 

gpr_$set_f ill_value (current_value, st) ; 

draw_triangle(i*100, i*50);, 

end; { for } 

{Next draw a five-plane image of overlapping triangles in planes 3-7. } 

plane_jrask := [3, 4, 5, 6, 7]; 

gpr_$set_plane_jrask(plane_jrask, st); 

for i := to 31 do begin { 32 colors } 

current_value := Ishftd, 3); 

gpr_$set_f ilL_value (current_value, st) ; 

draw_triangle(i*10, i*25); 

end; { for } 

{ Set up a five-second wait tiire. } 

wait_tiire.hi^6 := 0; 
wait_tiire.lcw32 := 5* one_seGond; 
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{ Now shew the first iirage and wait five seconds. } 



for i := to 255 do begin 
case (i & 7) of 
color_jrap [i 
color_jrap [i 
color_jrap [i 
color_jrap [i 
color_jrap [i 
color_jrap [i 
color_jrap [i 
color_jrap [i 
end; { case } 
{ for } 



0: 
1: 
2: 
3: 
4: 
5: 
6: 
7: 



{ Set up color irap to show planes 0-2. } 
{ Use the eight irajor colors } 

= gpr_$black; 

= gpr_$blue; 

= gpr_$green; 

= gpr_$cyan; 

= gpr_$red7 

= gpr_$nragenta; 

= gpr_$yellcw; 

= gpr_$white; 



end; 



gpr_$set_color_jrap(0, 256, color_jrap, st); 
tiire_$wait(tiire_$relative, wait_tiire, st); 

{ New shew the second iirage and wait five seconds. } 

diir.gray := 16 00080808; { gr^, 1/32 of white's intensity } 

for i := to 255 do begin { Set up color irap to show planes 3-7.} 

color_jrap[i] := rshft(i, 3) * diir_gray; { use gray scale } 

end; { for } 
gpr_$set_color_jrap(0, 256, color_jrap, st); 
tiire_^ait(tiire_$relative, wait_tiire, st); 

end; { if bitir_hi_plane = 7 } 

{ Tenrinate the use of graphics. } 

gpr_$tenrinate (false, st) 

end. { planes_exairpQ.e } 
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10.4 USING INHJT DEVICES 

Hiis prograir draws diagonal vectors as it iroves around a window. The user 
can interactively change raster operations ty pressing buttons on the irouse. 

prograir vectors; 

%nolist; 

%include '/sys/ins/base. ins. pas ' ; 

% incl ude ' /sy s/ins/gpr . ins. pas ' ; 

%include '/sys/ins/error . ins. pas' ; 

%list; 

const 

inc =32; 

var 

bitirap : gpr_$bitirap_desc_t; 

status : status_$t; 

size : gpr_$offset_t; 

line : boolean; 

loop : boolean; 

unobs : boolean; 

ev_type : gpr_$event_t; 

keystroke : char; 

position : gpr_$position_t; 

start, finish : gpr_$positioa_t; 

dir : (plus_x, plus_y, irinus_x, irinus_y) ; 

i : integer; 

buttons : gpr_$keyset_t := ['a' ,'b' ,'c' ,'A' ,'B' ,'C'] ; 

procedure check; 

begin 

if status. all <> status_$ok then 

error_$print (status); 
end; { procedure dheck } 

begin {progrsnr} 

{ Initialize to iraxiirur displayed window size. } 

size.x_size := 1024; 
size.y_size := 1024; 

{ Initialize GPR in direct irode for standard output. } 

gpr_$init (gpr_$directrstreair_$stdout,size,0, bitirap, status) ; 
check; 
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{ Find out the size of the bitirap. GER 
shrinks the bitirap to fit the window if necessary. } 

gpr_$inq_bitirap_diirensions (bitirap, size, i, status); 

check; 

writeln ('size :', size.K-Size, ' ty ', size.y_size); 

{ Set attributes for popping and auto- refresh. } 

gpr_$se t_obscur e<i_opt (gpr_$pop_if _obs , status ) ; 
gpr_$set_auto_refresh (true, status); 

{ Enable 'q' and 'Q' , buttons, and locator input. All other 
types of input go through the Display Manager. } 

gpr_$enable_input (gpr_$keystroke , [ *Q ' , ' q' ] f status ) ; 

check; 

gpr_$enable_input (gpr_$buttons, buttons, status); 

check; 

gpr_$enable_input (gpr_$locator , [ ] , status ) ; 

check; 

gpr_$enable_input (gpr_$locator_stop, [], status); 

check; 

{ Enable displ^ of the cursor. } 

gpr_$set_cursor_active (true, status); 
check; 

{ Initialize variables for the loop } 

loop := true; 

start. x_coord := 0; 

start.y_ooord := 0; 

finish. x_coord := size.x_size -• 1; 

finish. y_coord := size.y_size - 1; 

dir := plus_x; 

{ Aoguire the displ^ and begin the loop. } 

unobs := gpr_$aaquire_display (status); 

check; 

repeat 

{ Move to a new position and draw a vector. } 

gpr_§irove (start. K_cx)ord, start. y_ooord, status); 

check; 

gpr_$line (finish. x_ooord, finish. y_coord, status); 

check; 

{ The CASE staten^ent calculates the coordinates for the 
next vector. The starting point for the vector is 
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initially the i5)per left corner of the window: the 
vector iroves around the window f ror there. For exaFpLe, 
if the direction is positive for x (plus_x) , the 
x-coordinate of the starting point is incrorented 
ty inc, the x-coordinate of the ending point is 
decremented ty iric, and the y-coordinates regain 
constant. } 

case dir of 

plus_x : begin 

start. x_ooord := start. x_ooord + inc; 
finish. xL.coord := size.3Q_size - 1 - start. 3?_coord; 
if (start. x_coord >= size.x_size - 1) then begin 
start. x_coord := size.x_size - 1; 
finish. K_coord := 0; 
dir := plus_y; 
end; 
end; 
plus_y : begin 

start. y_coord := start. y_coord + inc; 
finish. y_ooord := size.y_size - 1 - start. y_coord; 
if (start. y_ooord >= size.y_size - 1) then begin 
start.y_coord := size.y_size - 1; 
finish. y_coord := 0; 
dir := irinus_x; 
end; 
end; 
irinus_x : begin 

if (start. x_coord <= inc) then begin 
start. x_ooord := 0; 
finish. 3L_coord := size.3e_size - 1; 
dir := irinus_y; 
end 
else begin 

start. x_coord := start. x_ooord - inc; 
finish. 3L_ooord := size.x_size - 1 - start. :L_coord; 
end; { if then else} 
end; 
irinus_y : begin 

if (start. y_ooord <= inc) then begin 
start. y_coord := 0; 
finish. y_coord := size.y_size - 1; 
dir := plus_x; 
end 
else begin 

start. y_coord := start. y_coord - inc; 
finish. y_coord := size.y_size - 1 - start. y_coord; 
end; {if then else} 
end; 
end; {case } 
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{ New look for user input. } 

unobs := gpr_$con<l_event_wait (ev_type, keystroke, position, status); 
check; 

case ev_type of 

{ Type 'q' or *Q' to exit frar the program. } 

gpr_$key stroke: begin 

case keystroke of 
'Q'r'q': loop := false; 
end; {case keystroke} 
end; {gpr_$key stroke } 

{ Move the cursor. } 

gpr_$locator : begin 

gpr_$set_cursor_position (position, status) ; 
end; 

{ Change the raster ops. } 

gpr_$buttons: begin 

case keystroke of 

'a* : gpr_$set_raster_op (0,1, status); 

*b' ! gpr_$set_raster_op (0,6, status); 

'c* : gpr_$set_raster_op (0,1 5, status); 
end; {case} 
end; {gpr_$buttons} 

end; {case ev_type} 
until not loop; 

{ Exit neatly; release the display and tenrinate the use of GFR. } 

gpr_$release_display (status); 

check; 

gpr_$tenrinate (true , status ) ; 

check; 

end. 
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10.5 USING HBBER Bi^SIDING 

The following program allows the user to draw lines on a ironochrcrratic 
displ^. As a line is being placed, you are provided with feedback known as 
'rubber banding'. This ireans that the line defined ty the first end point 
and the current location of the cursor is continually drawn and erased as a 
new cursor location is obtained. This is acooirplished fcy drawing and 
redrawing the saire line with the 'exclusive or' raster_op set. 

To begin or tenrinate lines, use either of the first two irouse buttons. Use 
the last irouse button to end the prograrr. Alternatively, you can use the 
first two prograir function keys to begin and tenrinate lines and the third 
function key to end the program. 

EROGJRAM rubberband; 

%nolist ; 

% include '/sys/ins/base. ins. pas' ; 
% include '/sys/ins/gpr. ins. pas' ; 
% include '/sys/ins/error. ins. pas' ; 
%include '/sys/ins/kbd. ins. pas' ; 
%list ; 

CDNST 

black = ; 
white = 1 ; 

VAR 

offset : gpr_$offset_t ; 

pos : gpr_$position_t ; 

i : integer ; 

b_desc : gpr_$bitirap_desc_t ; 

status : status_$t ; 

size: gpr_$offset_t; 

irousejDuttons : gpr_$keyset_t := ['a', 'b', 'c']; 

pfks : gpr_$keyset_t := [kbd_$fl, kbd_$f2, kba_$f3]; 

null^buttons : gpr_$keyset_t := [ ] ; 

first : boolean ; 

et : gpr_$event_t ; 

ed : char ; 

last, anchor : gpr_$position_t ; 

hose : boolean ; 

rect : gpr_$window_t; 

BBSIN 

offset. x_size := 800 ; 

offset.y_size := 800 ; 

gpr_$init (gpr_$borrow, 1, offset, 0, b_desc, status ) ; 

pos.X-OOord := 400 ; 

pos.y_ooord := 400 ; 



{ Place a filled object for visual interest.} 
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rect.wincbw_base.x_c»ord := 220; 
rect.window_base.y_cxx)rd := 180; 
rect.window_size.3L_size := 220; 
rect.window_size.y_size := 180; 
gpr_$rectangle ( rect, status); 

gpr_$enable_input ( gpr_$buttons, irouse_buttons, status ) ; 
gpr_$enable_input ( gpr_$key stroke, pfks, status ); 

REPEAT 

first := true ; 

{ Set 'exclusive or' raster op. } 

gpr_$set_raster_cp ( 0, 6, status ) ; 

{ Wait for the inital irouse key to begin. } 

gpr_$set_cursor_active ( true, status ) ; 

hose := gpr_$event_wait ( et, ed, pos, status ) ; 

gpr_$set_cursor_active ( false, status ) ; 

if ((ed = 'c') or (ed = kba_$f3)) then exit; 

anchor . x_ooord := pos.x_ooord ; 

anchor. y_ooord := pos.y_coord ; 

gpr_$rove ( anchor. x_ooord, anchor. y_ooord, status ) ; 

gpr_$enable_input ( gpr_$locator , nulL-buttons, status ) ; 

{ Rubberband to the locator position until irouse key. } 

REPEAT 

hose := gpr_$event_wait ( et, ed, pos, status ) ; 
IF et = gpr_$locator OHEN begin 
IF not first TBM begin 

gpr_$n[^ove ( anchor . x_ooord, anchor. y_ooord, status ) ; 
gpr_$line ( last.x_coord, last.y_ooord, status ) ; 
end 
ELSE 

first := false ; 

gpr_$set_draw_value ( white, status ) ; 

gpr_§irove ( anchor. x_ooord, anchor. y_ooord, status ) ; 

gpr_$line ( pos.x_ooord, pos.y_ooord, status ) ; 



last.x-coord := pos.x_ooord ; 
last.y_coord := pos.y_ooord ; 
end ; { if locator } 

UNTIL ((et = gpr_$buttons) or (et = gpr_$key stroke )) ; 

{ No/ really draw the line with nonral a raster_op. } 

gpr_$set_raster_op ( 0, 3, status); 

gpr_$irove ( anchor. x_coord, anchor. y_GOord, status ) ; 
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gpr_$line ( last.x_cx)ord, last.y_c»ord, status ) ; 

gpr_$disable_input ( gpr_$locator, status ) ; 
UMTIL false; 

gpr_$tenrinate ( false, status ) ; 

END. 



10.6 STOKENG A BITMAP EXTERNALLY 



The follcwing two exairples illustrate how to create of bitirap for external 
storage and copy it to a bitirap file. The second exairple shews how to access 
the stored bitirap and displ^ it. 



prograrr durrp_screen; 

%nolist; 

% include ' /sy s/ins/base . ins . pas ' ; 

% incl ude ' /sy s/ins/gpr . ins. pas ' ; 

%list; 



var 



window 

hi^lane 

groups 

bitirap 

status 

version 

header 

attribs 

filebr 

created 



gpr_$window_t 

gpr_$plane_t 

integer 

gpr_$bitirap_desc_t; 

status_$t; 

gpr_$versioiL_t ; 

gpr_$t8rf_group_header_ar ras^_t ; 

gpr_$attr ibute_desc_t ; 

gpr_$bitirap_desc_t; 

boolean; 



= [[0,0], [1024,1024]]; 
= 7; 
= 1; 



begin 

gpr_$init (gpr_$borrow_nc,l, window. window_size,hi_plane, bitirap, status) ; 

gpr_$inq_bitirap_diirensions (bitirap,window.window_size, lii_plane, status ) ; 



= hi_plane + 1; 

= l! 

= 
= 
= 



header [0] .rL.sects 

header [0] .pixel_size 

header [0] .allocated^size 

header [0] .bytes_per_line 

header [0] .l:]ytes_per_sect 

gpr_$allocate_attribute_block (attribs, status) ; 

{Use the access paraireter gpr_$create for creating a bitirap fUe.} 

gpr_$opeiL_bitarap_f ile (gpr_$create, ' screen^duirp. fcirf ' ,15, 

version, window. window_size, groups, header , 
attribs, filetir, created, status ) ; 
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gpr_$set_bitirap (filetir, status) ; 

gpr_$pixel_blt (bitmap, window , window. window_base , status ) ; 

end. 



This progrsn^ opens the created bitrrap file for display in read only irode. 



prograir show_screen; 

%nolist; 

%include Vsys/ins/base • ins. pas ' ; 

%include '/sys/ins/gpr . ins. pas ' ; 

%list; 



var 



window 


: gpr_$window_t := [[0,0],[1 


hl_plane 


I gpr_$plane_t := 7; 


groups ; 


: integer; 


bitirap j 


: gpr_$bitrrap_desc_t; 


status ; 


! status_$t; 


version : 


: gpr_$version_t; 


header : 


gpr $birf group header arr^ t; 


attribs ; 


gpr_$attribute_desc_t; 


filebr j 


gpr_$bi tirap_desc_t ; 


created : 


boolean; 



begin 

gpr_$init (gpr_$bor row,l ,window. window_size, hi^plane, bitirap, status ) ; 

gpr_$allocate_attribute_block (attribs, status) ; 

gpr_$open^bitirap_file(gpr_$readonly, *screen^durrp.tirf ' ,15, 

version,windcw.window_size, groups, header, 
attribs, filefcir, created, status ) ; 

gpr_$pixel^blt (f ilebr, window, window. window_base, status) ; 

end. 
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10.7 USING DISPLAY ^DDES 

Ihe choice of display irode depends on which characteristics work best with 
your grajiiics operation. The four irodes and their characteristics are as 
follcws. 

10.7.1 So rro w^Pi spl a y M ode 
A dv an ta ges 

• Allcws use of the entire screen 

• Gives control over the entire color irap. 

• Provides the option of not clearing the bitirap. 

Di sadvantages 

• Uses entire screen 

• Suspends Display Manager; other processes are not iinrediately available. 

Because of its full-screen display, borrcw-displ^ irode is useful for sore 
applications programs. Borrcw-displ^ acquires the displ^ hardware. This 
gives you control over the entire color irap, including the colors otherwise 
reserved for the displ^ iranager. However, other processes are not available 
until the borrcwing progrsnr returns the display. 

Borrcw-display irode is required for imaging formats because these f onrats 
reconfigure the entire refresh buffer. 

10.7.2 Dir ect M od e 

Advantages 

• Offers the performance of borrcw-display^ mode. 

• Can use any rectangular part of the screen. 

• Retains the use of the Display Manager. 

D i sadvan t ages 

Does not allcw control of the entire color map. 
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In direct irode, the program repeatedly acxjuires and releases the display for 
brief periods for grajiiics operations. This gives the advantages of speed 
of operation while preserving the Display Manager's control over display 
functions such as changing the window size and scrolling. Direct irode allows 
other processes to share the display. 



10.7.3 Fraire Mode 
Advantages 

• Reserves an area within a pad for graphics displ^. 

• C&n scroll an iirage out of view; redraws the iirage when it is pushed 
or popped. 

• Facilitates scaling. 

• Can use high-level I/O calls such as READ and WRITE 

• Can leave an iirage in the pad for later viewing 

Piisadvantages 

• PrograpT executes irore slowly than in borrow display irode. 

• "Player piano" effect: When an iirage has had irary changes since the 
last call to GPEL.$CLEAR, all such changes are played back. Ihis 
playing back, which occurs when the window is redrawn for any reason, 
ir^ take a noticeable period of tiire to coirplete. 

• Fraire irode places sore restrictions on GPR operations (see Section 
2.2.3 and descriptions of routines in Qiapter 11). 

Frame irode is generally considered the easiest to use. It is appropriate for 
siirple, noninteractive applications. 
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10.7.4 No-Display Mode 

• Allocates a bitirap f rar main irorory 

• Can perfonr graj^ic operations to the bitarap while bypassing the 
display. 

• C^n create bitoraps larger than the display. 

• C&n file the bitirap or send it to a peripheral device, such as a 
printer 

Disadvantages 

Does not displ^ iirages 
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CHAPTER 11 
USER CALLABLE ROUTINES 



This chapter describes graphics primitives routines in terms of format and 
parameters. The routines are organized alphabetically for reference. A 
listing by category introduces the routines. 



11.1 FUNCTIONAL LIST OF ROUTINES 

Use the following listing by functional category to help you find the 
routines you want. Some calls are included in more than one category. To aid 
identification, each call is described briefly. 

Initialize/Terminate Graphics Package 

GPR_$INIT 

Initializes the graphics primitives package. 

GPR_$TERMINATE 

Terminates the graphics primitives package. 

Inquire Display Configuration 

GPR_$INQ_OONFIG 

Gives the value of the current display configuration. 

Establish. Delete. Identify Bitmaps 

GPR_$ALLOCATE_BITMAP 

Allocates a bitmap in main memory and returns a bitmap descriptor. 

GPR_$ALLOCATE_BITMAP_NC 

Allocates a bitmap in main memory without setting all the pixels in the 
bitmap to zero, and returns a bitmap descriptor. 

GPR_$ALL0CATE_HDM_BI1MAP 

Allocates a bitmap in hidden display memory. 
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GPR_$DEALLOCATE_BITMAP 

Deallocates an allocated bitmap. 

GPR_$INa_BITMAP 

Returns the descriptor of the current bitmap. 

GPR_$INCLBI'IMAP_DI]yiENSIONS 

Returns the size and number of planes of a bitmap. 

GPR_$INQ_WINDOW_ID 

Returns the character that identifies the current bitmap's window. 

GPR_$0PEN_BI1MAP_FILE 

Opens a file for external storage of a bitmap. 

GPR_$SET_BITMAP_DIMENSIONS 

Modifies the size and the number of planes of a bitmap. 

GPR_$SET_WINDOW_ID 

Establishes the character that identifies the current bitmap's window. 

Access Bitmaps 

GPR_$ENABLE_DIRECr_ACCESS 

Ensures the completion of display hardware operations before the 
program uses the pointer to access display memory. 

GPR_$INQ_BITMAP_POINTER 

Returns a pointer to bitmap storage in virtual address space. This routine 
also returns the offset in memory from the beginning of one scan line 
to the next. 

GPR_$INQ_BM_BIT_OFFSET 

Returns the bit offset that corresponds to the left edge of a bitmap in 
virtual address space. 

GPR_$SET_BITMAP 

Establishes a bitmap as the current bitmap for subsequent operations. 

GPR_$REiyiAP_CDIiOR_MEM0RY 

Sets the single plane of color display memory to access directly. 

GPR_$REMAP_OOLOR_MEMORY_1 

Sets the plane of hidden color display memory. This plane is mapped 
at the address returned by GPR_$INQ_BI1MAP_IOINTER. 
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Establish, Delete, Identify Attribute Blocks 

GPR_$MIiC)CATE_ATTRIBinE_BLOCK 

Allocates a data structure that contains initial settings for bitmap 
attributes. The routine also returns the descriptor for the data 
structure. 

GPR_$ATTRIBUTE_BLOCK 

Returns the descriptor of the attribute block associated with the 
given bitmap. 

gpr_$dea]X(x:ate_attribute_block 

Deallocates an attribute block allocated by GPI^$ALLOCATE_ATTRIBUaE_BLOCK. 

gpr_$set_mtribute_block 

Associates an attribute block with the current bit map. 



Set Attributes 



GPR_$SET_CLIP_WINDCIW 

Changes the clipping window for the current bitmap. 

GPR_$SET_CLIPPING_ACTIVE 

Enables/disables a clipping window for the current bitmap. 

GPR_$SET_aX)RDINATE_ORIGIN 

Establishes x- and y-off sets to add to all x- and y-coordinates 
used as input for these operations: moving the current position, 
line drawing, and block transfers. 

GPR_$SET_DRfiW_VALUE 

Specifies the color/ intensity value to use to draw lines. 

GPR_$SET_FIIli_BACKGROUND_VALUE 

Specifies the color/ intensity value to use for drawing the background 
of tile fills. 

GPR_$SET_FILL_PATTERN 

Specifies the fill pattern to use for the current bitmap. 

GPR_$SET_FILL_VALUE 

Specifies the color/ intensity value to use to fill rectangles. 

GPR_$SET_LINE_PA'rTERN 

Establishes the pattern used in drawing lines. 

GPR_$SET_LINESTYLE 

Specifies the linestyle as solid or dashed. 
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GPR_$SET_PLANE_MASK 

Establishes a plane mask that specifies which planes to use for 
subsequent write operations. 

GPR_$SET_RASTER_OP 

Specifies a new raster operation for both BLTs and lines. 

GPR_$SET_TEXT_BACKGKXJND_YALUE 

Specifies the color/ intensity value to use for text background. 

GPR_$SET_TEXT_PONT 

Establishes a new font for subsequent text operations. 

GPR_$SET_1EXT_YALUE 

Specifies the color/intensity value to use for writing text. 



Retrieve Attributes 



GPR_$INQ_OONSTRAINTS 

Returns the clipping window and plane mask used for the current bitmap, 

GPR_$INQ_C0ORDINATE_ORIGIN 

Returns the x- and y-off sets added to all x- and y-coordinates used as 
input to move, line drawing, and BLT operations on the current bitmap. 

GPR_$INQ_DRAW_VMiUE 

Returns the color/ intensity value used for drawing lines. 

GPR_$INQ_FI]X_BACKGRaJlCLVMiUE 

Returns the color/ intensity value used for drawing the background of 
tile fills. 

GPR_$INQ_FILL_PATTERN 

Returns the fill pattern in use for the current bitmap. 

GPR_$INQ_FILL_VALUE 

Returns the color/ intensity value used for filling rectangles. 

GPR_$INQ_LINE_PATTERN 

Returns the pattern used in drawing lines. 

GPR_$INQ_LINESTYLE 

Returns the current line style. 

GPR_$INQ_RASTER_OPS 

Returns the raster operations in use for the current bitmap. 

GPR_$INQ_TEXT 

Returns the text font and text path used for the current bitmap. 
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GPIl_$INQ_TEXT_OFFSET 

Returns the x- and y-off sets from the top left pixel of a string to 
the origin of the string to be written by GPR_$TEXT to the origin of its 
first character. This routine also returns the x- or y-offset to the 
pixel which is the new current position after the text is written 
with GPR_$TEXT. 

GPR_$INQ_TEXT_VALUES 

Returns the current values of color/intensity for text and text 
background in the current bitmap. 

Color Operations 

GPR_$COLOR_ZOOM 

Sets the zoom scale factor for a color display. 

GPR_$SELECT_OOLOR_FRAME 

Selects whether frame or frame 1 of the color display memory is visible. 

Set/Inquire Color Map 

GPR_$SET_OOLOR_MAP 

Establishes new values for the color map. 

GPR_$INQ_C0LOR_iyiAP 

Returns the current color map values. 

Block Transfer (BLT) 

GPR_$AIX>ITIVE_BLT 

Adds the single plane of any bitmap to the current bitmap. 

GPR_$BIT_BLT 

Performs a bit block transfer from a single plane of any bitanap to a 
single plane of the current bitmap. 

GPR_$PIXEL_BLT 

Performs a pixel block transfer from any bitmap to the current bitmap. 

Set/Inquire Current Position 

GPR_$MOVE 

Changes the current position. 

GPR_$INQ_CP 

Returns the current position in the current bitmap. 
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Line Drawing Operations 

GPR_$ARC_3P 

Draws an arc from the current position, through two other points. 

GPR_$CIRCLE 

Draws a circle with a specified radius around a specif ed center point. 

GPR_$DRAW_BOX 

Draws an unfilled box given two opposing corners. 

GPR_$LINE 

Draws a line from the current position to the given position. The routine 
then updates the current position to the given position. 

GPR_$MULTILINE 

Draws a series of disconnected lines. 

GPR_$POLYLINE 

Draws a series of connected lines. 

GPR_$SELINE_CUBIC_P 

Draws a parametric cubic spline through the control points. 

GPR_$SPLI^E_aBIC_X 

Draws a cubic spline as a function of x through the control points. 

GPR_$SPLINE_aBIC_Y 

Draws a cubic spline as a function of y through the control points. 

Fill Operations 

GPR_$CIRCLE_FILLED 

Draws and fills a circle with a specified radius around a 
specified center point. 

GPIl_$RECrANGLE 

Fills a rectangle. 

GPR_$TRIANGLE 

Fills a triangle, 

GPR_$TE^APEZOID 

Draws and fills a trapezoid. 

GPR_$MULTITRAPEZOID 

Draws and fills a list of trapezoids in the current bitmap. 
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GPR_$START_PGai 

Defines the starting position to create a loop of edges for a 
polygon boundary. 

GPR_$PGai_POLYLINE 

Defines a series of line segments forming part of a polygon boundary. 

GPR_$CLOSE_FILL_PG0N 

Closes and fills the currently open polygon. 

GPR_$CLOSE_RETURM_PGai 

Closes the currently open polygon and returns the list of trapezoids 
within its interior. 

Text Operations 

GPR_$INQ_CHARACTER_WIDTH 

Returns the width of the specified character in the specified font. 

GPR_$INQ_HORIZ(»ITAL_SPACING 

Returns the parameter for the width of spacing between displayed 
characters for the specified font. 

GPR_$INQ_SPACE_SIZE 

Returns the width of the space to be displayed when a character 
requested is not in the specified font. 

GPR_$INa_TEXT 

Returns the text font and text path used for the current bitmap. 

GPR_$INQ_TEXT_EXTENT 

Returns the x- and y-off sets a string spans when written by GPIL.$TEXT. 

GPR_$INQ_1EXT_0FFSET 

Returns the x- and y-off sets from the top left pixel of a string to 
to the origin of the string's first character. This routine also returns 
the X- or y- offset to the pixel which is the new current position 
after the text is written with GPR_$TEXT. 

GPR_$INQ_TEXT_PATH 

Returns the direction for writing a line of text. 

GPR_$INa-TEXT_VALUES 

Returns the current values of color/ intensity for text and text 
background in the current bitmap. 

GPR_$LOAD_PONT_FILE 

Loads a font from a file into the display's font storage area. 

GPR_$REPLICATE_F(Mr 

Creates and loads a modifiable copy of a font. 
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GPR_$SET_aiARACTEIUi^IDTH 

Specifies the width of the specified character in the specified font. 

GPR_$SET_HORIZC»ITAL_SPACING 

Specifies the parameter for the width of spacing between displayed characters 
for the specified font. 

GPR_$SET_SPACE_SIZE 

Specifies the width of the space to be displayed when a character 
requested is not in the specified font. 

GPR_$SET_aEXT_EACKGROUND_VALUE 

Specifies the color/intensity value to use for text background. 

GPR_$SET_1EXT_F0NT 

Establishes a new font for subsequent text operations. 

GPR_$SET_TEXT_PATH 

Specifies the direction for writing a line of text. 

GPR_$SET_TEXTVALUE 

Specifies the col or/ intensity value to use for writing text. 

GPR_$TEXT 

Writes text in the current bitmap, beginning at the current 
position and proceeding in the direction specified by the most recent 
use of GPIl_$SET_TEXT_PATH. 

GPR_$UNLQADJONT_FILE 

Unloads a font that a program has loaded with GPR_$LQAD_FC»IT_FILE. 

Cursor Control 

GPR_$INQ_CURSOR 

Returns information about the cursor. 

GPR_$SET_ajRSOR_ACTIVE 

Specifies whether the cursor is displayed. 

GPR_$SET_ajRSOR_ORIGIN 

Defines one of the cursor's pixels as the cursor origin. 

GPR_$SET_ajRSOR_PATrERN 

Loads a cursor pattern. 

GPR_$SET_CURSOR_POSITION 

Establishes a position on the screen for display of the cursor. 
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Clear Pixel Values 

GPR_$CLEAR 

Sets all pixels in the current bitinap to the given color/intensity value. 

ReacVWrite Pixel Values 

GPR_$READ_PIXELS 

Reads the pixel values from a window of the current bitmap and stores 
the values in the pixel array. 

GPR_$WRITE_PIXE1LS 

Writes the pixel values from a pixel array into a window of the current 
bitmap. 

Postpone Color Display Modification 

GPR_$WMT_FRAME 

Waits for the current frame refresh cycle to end before executing 
operations that modify the color display. 

Input Operations 

GPR_$CCMD_EVENT_WAIT 

Returns information abut the occurrence of any event without entering 
a wait state. 

GPR_$DISABLE_INPUT 

Disables a previously enabled event type. 

GPR_$ENABLE_INPUT 

Enables an event type and a selected set of keys. 

GPR_$EVENT_WAIT 

Waits for an event or until a time-out value is reached. 

GPR_$GET_EC 

Returns the address of the event count associated with a graphic event. 

GPR_$SET_INPUT_SID 

Specifies the input pad from which programs take graphics input. 
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Direct Graphics Operations 

GPR_$ACQUIRE_DISHiAY 

Establishes exclusive access to the display hardware and the display 
driver. 

GPR_$FORCE_RELEASE 

Releases the display regardless of how many times is has been acquired. 

GPR_$INQ_VIS_LIST 

Returns a list of visible sections of an obsured window. 

GPR_$RELEASE_DISPLAy 

Decrements a counter associated with the number of times a display tas 
been acquired. 

GPR_$SET_ACQ_TIME_OUT 

Establishes the length of time for which the program can acquire the 
display. 

GPR_$SET_AU'ro_REFRESH 

Directs the Display Manager to refresh the window automatically. 

GPR_$SET_OBSaJRED_OPr 

Establishes the action the program is to take when a window to be acquired 
is obscured. 

GPR_$SET_REFRESH_ENTRY 

Specifies the entry points of these application-supplied procedures: 
refreshing the displayed image in a direct window and refreshing the 
hidden display memory. 

Set. Inquire Imaging Format 

GPR_$SET_Iiy!AGING_FORMAT 

Sets the imaging format of the color display. 

GPR_$INQ_IiyiAGING_JX3RMAT 

Returns the current imaging format of the color display. 

GPR_$SET_a)LOR_MAP 

Establishes new values for the color irap. 

11.2 DESCRIPTION OF ROUTINES 



The ronainder of this chapter describes graphics primitives routines. The 
descriptions are organized alphabetically for reference. 
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GPR_$ACQUIRE_DISPLAy 



GPR_$AOQUIRE_DI SPLAY -— Establishes exclusive access to the display 

hard/are and the display driver. 

FORMAT 

unobscured := GPR_$ACQUIRE_DI SPLAY (status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

unobscured 

A Boolean value that indicates whether or not the window is obscured 
(false=obscured) . This parameter is always true unless the option 
GPIl_$OK_IF_OBS was specified to GPR_$SET_OBSaiRED_OPT. 

status 

Completion status, in STATUS_$T format. A nonzero status indicates that 
the display was not acquired. 

NOTES 

* While the display is acquired, the Display Manager cannot run. Hence, 
it cannot respond to pad calls or to stream calls to input or transcript 
pads. If you need to call any of these routines, you must release the 
display to do so. 

* Since no other display output can occur while the display is acquired, 
it is not a good idea to acquire the display for long periods of time. 
The acquire routine autonatically times out after a default period of 
one minute; programs can change this time-out with the routine 
GPR_$SET_AOQ_TIME_OUT. 

* Although this call is needed only in direct mode, it can be called from 
any of the other display modes, where it performs no operation and 
returns the status code GPR_$NOT_IN_DIRECT_MDDE. 

* If the display is alrea(^ acquired when this call is made, a count of 
calls is incremented such that pairs of acquire/ release display calls 
can be nested. 
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GPR_$AIX)ITIVELBLT 



GPR_$ADDITIVE_BLT — Adds a single plane of any bitmap to the current 

bitmap. 

FORMAT 

GPR_$AEOITIVE_BLT (source-bitmap-desc, source-windoWf source-plane, 

dest-origin, status) 

INPUT PARAMETERS 

source-bitmap-desc 

Descriptor of the source bitmap which contains the source window to be 
transferred, in GPR_$BI'IMAP_DESC_T format. This is a 4-byte integer. 

source-window 

Rectangular section of the bitmap from which to transfer pixels, in 
GPR_$WINDOWLT format. This is a two-element array of two-element 
arrays. (In FORTE^AN, you can use a two-dimensional array.) 

The first element of GPR_$WINDCW_T specifies the window start origin 
(top left corner) , in GPR_$P0SITI0N_T format. This is a two-element 
array of 2-byte integers. The first element is the origin's 
x-coordinate; the second element is the y-coordinate. Coordinate values 
must be within the limits of the source bitmap. 

Ohe second element of GPIi_$WINDCW_T specifies the window width and 
height, in GPR_$OFFSET_T format. This is a two-elonent array of 2-byte 
integers. The first element is the window width, in raster units; the 
second element is the window height, in raster units. 

source-plane 

The identifier of the source plane to add, in GPR_$PLANE_T format. This 
is a 2-byte integer. Valid values are in the range through the 
identifier of the source bitmap's highest plane. 

dest-origin 

Start position (top left coordinate position) of the destination 
rectangle, in GPR_$POSITION_T format. This is a two-element array of 
2-byte integers. Ihe first element is the origin's x-coordinate; the 
second element is the y-coordinate. Coordinate values must be within 
the limits of the current bitmap, unless clipping is enabled. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 
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GPR_$ADDITIVE_BLT 



NOTES 

* Both the source and destination bitmaps can be in either display memory 
or main memory. 

* The source window origin is added to the coordinate origin for the 
source bitmap, and the result is the actual origin of the source 
rectangle for the BLT. Similarly, the destination origin is added to 
the coordinate origin for the current bitmap, and the result is the 
actual origin of the destination rectangle for the BLT. 

LIMITATIONS 

* If the source bitmap is a Display Manager frame, the only allowed raster 
op codes are 0, 5, A, and F. These are the raster operations in which 
the source plays no role. 

* If a rectangle is transferred by a BLT to a display iranager frame and 
the frame is refreshed for any reason, the BLT is re-executed. 
Therefore, if the information in the source bitmap has changed, the 
appearance of the frame changes accordingly. 
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GPR_$MiLOCATE_ATTRIBUTE_BLOCK 



GPR_$AIJX)CATE_AITRIBUTE_BLCOC — Allocates a data structure that contains 

initial bitmap attribute settings, and 
returns the descriptor for the data 
structure. 



FORMAT 

GPR_$AlX(XATE_ATTRIBUaE_BLC)CK (attrib-block-desc, status) 

INPUT PARAMETERS 
None 

OUTPUT PARAMETERS 

attrib-block-desc 

Attribute block descriptor, in GPR_$A1TRIBUTE_DESC_T fomiat. This is a 
4-byte integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* When allocated, the attribute block is initialized to default settings. 
See Section 3.7.2 for the default settings. 

* To associate an attribute block with the current bitmap, use 
GPR_$SET_ATTRIBUTE_BLOCK. 

* To deallocate an attribute block, use GPI^$DEALLOCATE_ATTRIBUTE_BLOCK. 
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GPR_$ALLOCATE_BI'IMAP 



GPR_$AIIiOCATE_BITMAP — Allocates a bitmap in main memory and returns a 

bitmap descriptor. 

FORMAT 

GPR_$ALLOCATE_BI'IMAP (size, hi-plane-id, attrib-block-desc, bitmap-desc, status) 

INPUT PARAiVlETERS 

size 

Bitmap width and height , in GPR_$OFFSET_T format. This is a two-elenent 
array of 2-byte integers. The first elanent is bitmap width, in raster 
units; the second element is the bitmap height, in raster units. 
Possible values for x are 1-4096; possible values for y are 1-4096. 

hi-plane-id 

Identifier of the highest plane which the bitmap will use, in 
GPR_$PLA^E_T format. This is a 4-byte integer. Valid values are 0-7. 

attr ib-block-desc 

Descriptor of the attribute block which the bitmap will use, in 
GPR_$ATTRIBUTE_DESC_T format. This is a 4-byte integer. 

OUTPUT PARAMETERS 

bitmap-desc 

Descriptor of the allocated bitmap, in GPR_$BI1MAP_DESC_T format. Tliis 
is a 4-byte integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To deallocate a bitmap, use GPR_$DEALL0CATE_BI13yiAP. 

* A program can not use a bitmap after it is deallocated. 

* To establish an allocated bitmap as the current bitmap, use 
GPR_$SET_BITMAP. 
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GPR_$ALLOCATE_BITMAP_NC 



GPR_$MjL0CATE_BIOT1AP_NC — Allocates a bitmap in itain memory without setting 

all the pixels in the bitmap to zero, and returns 
a bitmap descriptor. 

FORMAT 

GPR_$ALL0CATE_BI1MAP_NC (size, hi-plane-id, attrib-block-desc, bitmap-desc, stat 

INPUT PARAMETERS 

size 

Bitmap width and height, in GPR_$OFFSET_T format. This is a 
two-element array of 2-byte integers. The first element is bitmap 
width, in raster units; the second element is the bitmap height, in 
raster units. Possible values for x are 1-4096; possible values for 
y are 1-4096. 

hi-plane-id 

Identifier of the highest plane which the bitmap will use, in 
GPR_$PLANE_T format. This is a 4-byte integer. Valid values are 
0-7. 

attrib-block-desc 

Descriptor of the attribute block which the bitmap will use, in 
GPR_$ATTRIBUaE_DESC_T format. Tliis is a 4-byte integer. 

OUTPUT PARAMETERS 

bitmap-desc 

Descriptor of the allocated bitmap, in GPI^$BI1MAP_DESC_T format. 
This is a 4-byte integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To deallocate a bitmap, use GPR_$DEALL0CATE_BI1MAP. 

* A program can not use a bitmap after it is deallocated. 

* To establish an allocated bitmap as the current bitmap, use 
GPR_$SET_BI'IMAP . 

* GPR_$AIiLOCATE_BiaMAP sets all pixels in the bitmap to zero; this 
routine does not. As a result, GPI^$ALLOCfiLTE_BnMAP_NC executes 
faster, but the initial contents of the bitmap are unpredictable. 
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GPR_$AIliOCATE_HDM_BITMAP 



GPR_$ALLOCATE_HDM_BnMAP — Allocates a bitmap in hidden display memory. 



FORMAT 

GPR_$AIiLOCATE_HDM_BI'IMAP (size, hi-plane-id, attribHDlock-desc, bititap-desc, 

status) 



INPUT PARAMETERS 

size 

The width and height of the bitmap, in GPR_$OFFSET_T format. This is a 
two-elonent array of 2-byte integers. The first element is the bitmap 
width, in raster units; the second element is the bitmap height, in 
raster units. 

hi-plane-id 

The identifier of the highest plane of the bitmap, in GPI^$PIiANE_T 
format. This is a 2--byte integer. 

attrib-block-desc 

The descriptor of the bitmap's attribute block, in GPIL$ATTRIBUTE_DESC_T 
format. This is a 4-byte integer. 



OUTPUT PARAMETERS 

bitmap-desc 

The descriptor of the bitmap in hidden display memeory, in 
GPR_$BnMAP_DESC_T format. This is a 4-byte integer. 

status 

Coirpletion status, in STATUS_$T format. 

NOTES 

* GPR_$AIiLOCATE_HDM_BIlMAP allocates a GPR bitmap in hidden display memory 
for programs in bor row-display or direct mode. In frame mode, hidden 
display memory bitmaps cannot be used. 

* In direct mode you must acquire the display before calling 
GPR_$ALLOCATE_BI'IMAP . 

* The maximum size allowed for hidden display memory bitmaps is 224 bits 
by 224 bits. 

* Use GPR_$DEALLOCATE_BI'IMAP to deallocate a hidden display bitmap. 
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GPR_$ARC_3P 



GPR_$ARC_3P — Draws an arc from the current position through two other 
specified points. 



FORMAT 

GPI^$ARC_3P (point-2, point-3, status) 

INPUT PARAMETERS 

point-2 

The second point on the arc, in GPR_$POSITION_$T format. This is a 
two-element array of 2-byte integers describing an (x, y) coordinate 
position in the bitmap. Its values must be within bitmap limits unless 
clipping is enabled. 

point-3 

The third point on the arc, in GPR_$POSITION_T format. This is a 
two-element array of 2-byte integers, describing an (x, y) coordinate 
position in the bitmap. Its values must be within bitmap limits unless 
clipping is enabled. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 



The coordinates you specify are added to the corresponding elements of 
the coordinate origin for the current bitmap. The resultant coordinate 
positions are the points through which the arc is drawn. 

After the arc is drawn, point-3 becomes the current position. 

An error is returned if any of the three points are equal. 

When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. with clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPR_$ATTRIBU'rE_BLOCK 



GPR_$ATTRIBUTE_BLOCK — - Returns the descriptor of the attribute block 

associated with the given bitmap. 



FORMAT 

attrib-block-desc = GPR^$ATTRIBU1E_BL0CK (bitirap-desc, status) 

INPUT PARAMETERS 

bititap-desc 

Descriptor of the bitmap that is using the requested attribute block, in 
GPR_$BITMAP_DESC_T format. This is a 4~byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

RETORNED FUNCTION VALUE 

attr ib-block-desc 

Descriptor of the attribute block used for the given bitmap, in 
GPR_$Aa:TRIBUTE_DESC_T format. This is a 4-byte integer. 



NOTES 

* To set an attribute block as the block for the current bitmap, use 
GPR_$SET_ATTRIBUTE_BLOCK . 
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GPR_$BIT_BLT 



GPR_$BIT_BLT — Performs a bit block transfer from a single plane of any 
bitmap to a single plane of the current bitmap. 

FORMAT 

GPR_$BIT_BLT (source-bitmap-desc, source-window, source-plane, 
dest-origin, dest-plane, status) 

INPUT PARAMETERS 

source-bitmap-desc 

Descriptor of the source bitmap which contains the source window to be 
transferred, in GPR_$BiaMAP_DESC_T format. This is a 4-byte integer. 

source-window 

Rectangular section of the bitmap from which to transfer pixels, in 
GPR_$WINDCWLT format. This is a two-elonaent array of two-element 
arrays. (In FORTRAN, you can use a two-dimensional array.) 

The first element of GPR_$WINDCW_T specifies the window start origin 
(upper top corner) , in GPR_$POSITION_T format. This is a two-element 
array of 2-byte integers. The first element is the origin's 
x-coordinate; the second element is the y-coordinate. Coordinate values 
must be within the limits of the source bitmap. 

The second element of GPR_$WINDOW_T specifies the window width and 
height, in GPR_$OFFSET_T format. This is a two-elenent array of 2-byte 
integers. The first el orient is the window width, in raster units; the 
second element is the window height, in raster units. 

source-plane 

Identifier of the single plane of the source bitmap to move, in 
GPR_$PLANE_T fonnat. This is a 2-byte integer. Valid values are in the 
range through the identifier of the source bitmap's highest plane. 

dest-origin 

Start position (top left coordinate position) of the destination 
rectangle, in GPR_$POSITION_T fonnat. This is a two-element array of 
two-byte integers. The first element is the origin's x-coordinate; the 
second element is the y-coordinate. Coordinate values must be within 
the limits of the current bitmap, unless clipping is enabled. 

dest-plane 

Identifier of the plane of the destination bitmap, in GPIl_$PLANE_T 
format. This is a 2-byte integer. Valid values are in the range 
through the identifier of the destination bitmap's highest plane. 
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GPIi_$BIT_BLT 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 



* Both the source and destination bitmaps can be in either display memory 
or main memory. 

* The source window origin is added to the coordinate origin for the 
source bitmap, and the result is the actual origin of the source 
rectangle for the BLT. Similarly, the destination origin is added to 
the coordinate origin for the current bitmap, and the result is the 
actual origin of the destination rectangle for the BLT. 



LIMITATIONS 

* If the source bitmap is a Display Manager frame, the only allowed raster 
op codes are 0, 5, A, and F. These are the raster c^rations in which 
the source plays no role. 

* If a rectangle is transferred by a BLT to a Display Manager frame and 
the frame is refreshed for any reason, the BLT is re-executed. 
Therefore, if the information in the source bitmap has changed, the 
appearance of the frame changes accordingly. 
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GPR_$CIRCLE 



GPR_$CIRCIjE — Draws a circle with the specified radius around the specified 
center point. 

FORMAT 

GPR_$CIRCLE (center, radius, status) 

INPUT PARAMETERS 

center 

The center of the circle, in GPR_$POSITION_T format. This is a 
two-element array of 2-byte integers, describing an (x, y) coordinate 
position in the bitmap. Its values must be within bitmap limits unless 
clipping is enabled. 

radius 

The radius of the circle. This is a 2-byte integer in the range 
1-32767. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 

* The coordinates you specify are added to the corresponding elements of 
the coordinate origin for the current bitmap. The resultant coordinate 
position is the center of the circle. 

* The current position is not changed by use of GPIl_$CIRCLE. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPIl_$CIRCLE_FILLED 



GPR_$CIRCLE_FILLED — Draws and fills a circle with the specified radius 

around the specified center point. 

FORMAT 

GPR_$CIRCLE_FIIiLED (center, radius, status) 

INPUT PARAMETERS 

center 

The center of the circle, in GPR_$P0SITI0N_T format. This is a 
two-element array of 2-byte integers describing an (x, y) coordinate 
position in the bitmap. Its values must be within bitmap limits unless 
clipping is enabled. 

radius 

The radius of the circle. This is a 2-byte integer in the range 
1-32767. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 

* The coordinates you specify are added to the corresponding elements of 
the coordinate origin for the current bitmap. The resultant coordinate 
position is the center of the circle. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GHl_$CLEAR 



GEE^$CLEAR — Sets all pixels in the current bitipap to the given 
col or/ intensity value. 

GEEL.$CLEAR (index, status) 

INPUT PARAMETERS 

inc3ex 

New cx)lor map index specifying a col or/ intensity value for all pixels in 
the current bitmap, in GEEl_$PIXEI<_VALUELT format. This is a 4-byte 
integer. Valid values are: 

0-1 for monochromatic displays 

0-15 for color displays in 4-bit pixel format 

0-255 for color displays in 8-bit or 24-bit pixel format 

-2 for all displays. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

t ^Q TE S 

* A special case occurs if the specified index is -2. A value of -2 
specifies clearing the bitmap to the current background color/intensity 
value. For memory bitmaps and borrowed displays, the background 
col or/ intensity index is zero. For Display Manager frames, the 
background col or/ intensity value is the same as that used for the window 
background color. 

* For monochromatic displays, only the lew-order bit of the color value is 
considered, because bitmaps currently have only one plane. For color 
displays in 4-bit pixel mode, only the four lowest-order bits of the 
color value are considered because these displays have four planes. 

* You can use GPR_$SEaL03L0R_MAP to establish the correspondence between 
color map indexes and col or/ intensity values. This means that you can 
use GEE^$SET_aDLOR_MAP to assign the pixel value to bright intensity, 
and then use GPR^$CLEAR either to make the screen bright by passing the 
pixel value 0, or make the screen dark by passing the value 1. 

* This routine is subject to the restrictions of the current clipping 
window and plane mask. 

* The color specification parameter is a color map index, not a color 
value. See Section 4.3. 
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GPFL$CLOSE_FILL_PGON 

GHl_$CLOSE_FILI<_IGCN ~ Qoses and fills the currently open polygon. 

F OPMAT 

GI>R_$CLOSELFILl4_PG0N (status) 

None. 

O UTPUT P AR A METER g 

status 

CosonpLetion status, in STAIUS_$T format. 

NOTES 

* GPIL.$CLOSE_FlLli_IG0N closes and fills the series of polygon boundaries 
created with the routines GER_$START_PGON and GP!R_$PGaSLK)LYLINE. 

* GHl_$CLOSE_FIlJu_lGC»I does not use the current raster operation setting. 
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GPR_$CLOSE_RETURN_K30N 



GPR_$CLOSE_EETURN_PG0N — Closes the currently open polygon and returns the 

list of trapezoids within its interior. 

FORMAT 

GPR_$CLOSE_RETURN_PGON (list-size, trapezoid-list, trapezoid-number, status) 

INPUT PARAMETERS 

list-size 

The maximum number of trapezoids that the routine is to return. This is 
a 2-byte integer. 

OUTPUT PARAMETERS 

trapezoid-list 

The trapezoids returned. This is an array of trapezoids in GPR_$TRAP_T 
format, which is a two-element array in GPR^$EDRIZ_SEG_T format. The 
first element is the top horizontal segment of a trapezoid; the second 
element is the bottom horizontal segment. 

trapezoid-number 

The number of trapezoids that exist within the polygon interior. This 
is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 

tOTES 

* GPR_$CLOSE_RETURtL.PGaJ returns a list of trapezoids within a polygon 
interior that the graphics program can draw at a later time with the 
routine GPR_$MULTITRAPEZOID. 

* The trapezoid-number parameter is always the total number of trapezoids 
composing the polygon interior. If this number is greater than the 
list-size parameter, some trapezoids were left out of the trapezoid-list 
for lack of space. 
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GPIL$COriOR_ZOQM 



GPR_$C0L0I^Z00M — Sets the zoom scale factor for a color display. 

FORMAT 

GPR_$CDIiOR_ZOOM (xf actor, yf actor, status) 

INPUT PARAMETERS 

xfactor 

A 2-byte integer that denotes the scale factor for the x-coordinate, in 
the range 1 through 15. 

yfactor 

A 2-byte integer that denotes the scale factor for the y-coordinate, in 
the range 1 through 15. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* If the X value is not equal to 1, then the y value must be not equal to 
1. 

* GPR^$COLOR_ZOOM uses the integer zoom feature of the color hardware. 

* GPR_$CX)IiOR_ZO0M works only in borrow^display mode. 

* GPR_$COLOR_ZOOM always zooms from the upper-left corner of the display. 
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GPR_$COND_EVENT_WAIT 



GPR_$CCM)_EVENT_WAIT — Returns information about the occurrence of any event 

without entering a wait state. 

FORMAT 

unobscured := GPR_$CXM)_EVENT_WAIT (event-type, event-data, position^ status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

event_type 

The type of event that occurred, in GPI^$EVENT_T format. The possible 
events are: 

GPR_$KEySTROKE Input from a keyboard 

GPR_$BUTTONS Input from mouse or bitpad puck buttons 

GPR_$LOCATOR Input from a touchpad or mouse 

GPR_$ENTERED_WINDaw Cursor has entered window 

GPR_$LEFT_WINDCW Cursor has left window 

GPrL$LOCAT0IL.STDP Input from a locator has stopped 

GPR_$NO_EVENT No event has occurred 

event_data 

The keystroke or button character associated with the event, or the 
character that identifies the window associated with an entered window 
event. This parameter is not modified for other events. In FORTE^AN, 
this is declared as a character*l variable. 

position 

The position on the screen or within the window at which graphics input 
occurred, in GPR_$P0SITI0N_T format. Hiis is a two-element array of 
2-byte integers. 

unobscured 

A Boolean value that indicates whether or not the window is obscured; a 
false value means that the window is obscured. Iliis value is always 
true unless the program has called GPIL.$SET_OBSCURED_OPT and specified 
an option of GPR_$OK_IF_OBS. 

status 

Completion status, in STATUS_$T format. 
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GPR_$COND_EVENTWAIT 



NOTES 



* When called, this routine returns immediately and reports information 
about any event that has occurred. Typically, this routine is called 
following return from an EC2_$WAIT call involving the eventcount 
returned by GPR_$GET_EC. The routine allows the program to obtain 
information about an event without having to suspend all of its 
activities. 

* Unless locator data has been processed since the last event was 
reported, "position" will be the last position given to 
GPR_$SET_ajRSOR_POSITION. 

* If locator data is received during this call, and GPIl_$LOCATOR events 
are not enabled, the GPR software will display the arrow cursor and will 
set the keyboard cursor position. 

* Although this call never waits, it may release the display if it 
receives an unenabled event that needs to be handled by the Display 
Manager. 

* The input routines report button events as ASCEI characters. "Down" 
transitions range from "a" to "d"; "up" transitions range from "A" to 
"D". The three mouse keys start with (a/A) on the left side. As with 
keystroke events, button events can be selectively enabled by specifying 
a button keyset. 
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GPR_$DEALLOCATE_ATTRIBUTELBLOCK 



GPR_$DEAIjL(X:ATE_ArTRIBllTE_BLC)CK — Deallocates an attribute block allocated 

by GPI^$ALLCX3^TE_MTRIBU1E_BL0CK. 



FORMAT 

GPR_$DEMiL(X:ATE_ATTRIBUTE_BLCOC (attrib-block-desc, status) 

INPUT PARAMETERS 

attribHDlock-desc 

The descriptor of the attribute block to deallocate, in 
GPR_$ATTRIBUTE_DESCLT format. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To allocate an attribute block, use GPiL.$ALLOCATE_ArTRIBUTE_BLOCK. 

* To associate an attribute block with the current bitmap, use 
GPR_$SET_ATrRIBUTE_BLOCK . 
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gpii_$deallocate_bi™ap 

GPR_$DEALLOCATE_BnMAP — Deallocates an allocated bitmap. 

FORMAT 

GPR_$DEAIiLOCATE_BITMAP (bitnap-desc, status) 

INPUT PARAMETERS 

bitmap-desc 

Descriptor of the bitmap to deallocate, in GPR_$BITMAP_DESC_T format. 
This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Conpletion status, in STATUS_$T format. 

NOTES 

* To allocate a bitmap, use GPIl_$ALLOCATE_BnMAP or 

GPIL$ALL0CATE_HDM_BI1MAP . 
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GPR_$DISABLE_INPUT 



GPR_$DISABLE_INPUT — Disables a previously enabled event type. 

■ FORMA T 

GPR_$DISABLE_INPUT (event_type, status) 

INPUT PARAMETERS 

event_type 

The type of event to be disabled, in GPR_$EVENT_T format. The types of 
events are: 

GPR_$KEYSTROKE Input from a keyboard 

GPR_$BUTDONS Input from mouse or bitpad puck buttons 

GPR_$LOCATOR Input from a touchpad or mouse 

GPR_$ENTERED_WINDCW Cursor has entered window 

GPR_$LEFT_WINDCIW Cursor has left window 

GPIi_$IiOCATOR_STOP Input from a locator has stopped 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 



Following this call, no events of the given event type will be returned 
by GPR_$EVENT_WAIT or GPR_$C(MD_EVENT_WAIT. 

In bor row-display mode, disabled events received by the GPR software 
will be ignored. 

In direct mode or frame mode, disabled keystroke or button events are 
processed by the Display Manager. 

When locator events are disabled, the GPR software will display the 
arrow cursor and will set the keyboard cursor position when locator data 
is received. 
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GPR_$DRAWLBOX 



GPR_$DRAW_BOX — Draws an unfilled box based on the coordinates of two 
opposing corners, 

FORMAT 

GPR_$DRM_BOX (corner-1, corner-2, status) 

INPUT PARAMETERS 

corner-1 

Tflie corner of the box, in GPR_$P0SITI0N_T format. Uiis is a 
two-element array of 2-byte integers describing an (x, y) coordirate 
position in the bitmap. Its values must be within bitmap limits unless 
clipping is enabled. 

corner-'2 

An opposing corner of the box, in GPR_$POSITION_T format. Hiis is a 
two-elonent array of 2-byte integers, describing an (x, y) coordinate 
position in the bitmap. Its values must be within bitmap limits unless 
clipping is enabled. 

OUTPUT PARAMETERS 

status 

CoiT5)letion status, in STATUS_$T format. 



NOTES 

* The coordinates you specify are added to the corresponding elements of 
the coordinate origin for the current bitmap. The resultant coordinate 
positions are the opposing corners of the box. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPR_$ENABLE_DIRECr_iCCESS 



GPR_$ENABLE_DIRECr_ACCESS — Ensures cjonpletion of display hardware 

operations before program uses pointer to access 
display memory. 

FORMAT 

GPR_$ENABLE_DIRECT_ACCESS (status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NOTES 



If a program uses the GPR_$INQ_BIIMAP_POINTER to get the address of 
display memory for a monochromatic or color display, it should call 
GPR_$ENABLE_DIRECT_ACCESS after any calls that change the display and 
before using the pointer returned from the GPR_$INQ_BI1MAP_P0INTER. 
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GIR_ $ENABLE_ INHJT 



GPR.$ENABLE_INHJT — Enables an event type and a selected set of keys. 

FORMAT 

GPR_$ENABLE_ INHJT (event. type, key-set, status) 

INPUT PARAMETERS 

event_tYpe 

The type of event to be enabled, in GHL$EVENT_T format. The types of 
events are: 

GPR_$KEySTROKE Input from a keyboard 

GHL$Bl7nDNS Input from mouse or bitpad puck buttons 

GHL$LCXATOR Input f rem a touchpad or mouse 

GPR_$ENTERED_WINDCIW Cursor has entered window 

GPR_$LEPr_WINDOW Cursor has left window 

GPR.$LCXATOR_STOP Input from a locator has stopped 

key- set 

The set of specifically enabled characters when the event class is in 
GPR_$KEYSET_T format. This parameter is specified for event types of 
GPR_$KEYSTROKE and GPR_$BUTTONS. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS. $T format. 



NOTES 



This routine specifies the type of event and event input for which 
GHL$EVENT_WAIT is to wait. 

This routine applies to the current bitmap. However, enabled input 
events are stored in attribute blocks (not with bitmaps) in much the 
same w^ as attributes are. When a program changes attribute blocks 
for a bitmap during a grajiiics session, the input events you enabled are 
lost unless you enable those events for the new attribute block. 

Programs must call this routine once for each event type to be enabled. 

No event li^pss are enabled fcy default. 

The keyset must correspond to the specified event type. For example, 
use [' '..'"''] (in Ifescal) to enable all normal printing grajiiics. Use 
[chr(O) ..chr(127)] to enable the entire ASCII character set. Except in 
borrow-displ^ mode, it is a good idea to leave at least the O© and 
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GPR_$ENABLE_INPUT 



NEXTJWINDCIW keys out of the keyset so that the user can access other 
Display Manager windows. 

The insert file /SYS/INS/KBD.INS contains definitions for the non-ASCII 
keyboard keys in the range 128.. 255. 

Events and keyset data not enabled with this routine will be handled by 
the Display Manager in frame or direct mode and discarded in 
bor row-display mode. 

When locator events are disabled, the GPR software will display the 
arrow cursor and will set the keyboard cursor position when locator data 
is received. 

GPR_$ENABLE_INPUT expects a Pascal set of characters as one input 
argument. The following subroutine provides a way to build a set of 
characters for a FORERAN program using this call. 



BUIIiD_SET — Builds a Pascal set of characters for FORTOAN users. 

INPUT ARGUMENTS 

list — An integer*2 array, up to 256 entries long. 

This array contains the ordinal values of the 
characters to be included in the set. For 
example, if you wish to include the capital 
letters A through Z, make the array 
26 entries long, including the values 65 
through 90. 

no_of_entries — The number of entries used in list. 
An integer *2 scalar. 

OUTPUT ARGUMENTS 

returned_set — The equivalent of the Pascal set of 
characters. This can be of any type, 
as long as it is 32 bytes long. 
Use integer *4 returned_set(8) . 

This program does not check for errors. Therefore, values 
can be outside the range to 255, although this can give 
unpredictable results. The program does not check to see 
if the value has already appeared in the list. 

The subroutine builds the set anew each time; it does not allow 
you to add new elements to an existing set. 

The following program builds a set of characters for FORTRAN users. 

PROGRAM build set 



User Callable Routines 11-36 



GPR_$ENABLE_INPUT 



subroutine build_set (list , no_of_entr ies , returned_set) 

integer *2 list ( 1 ) , no_of_entr ies , returned_se t ( : 15 ) 
integer*2 i,nask(0:15) ,word,bit 

data inask/l,2,4,8,16#10,16#20,16#40,16#80,16#100,16#200, 
1 16#400rl6#800,16#1000,16#2000,16#4000,16#8000/ 

c A Pascal set of characters is a 256-bit "array." The bit 

c corresponding to the ordinal position of the character is 

c 1 if the bit is in the set and if the character is absent 

c from the set. In this example, the set is initialized 

c to 0, that is, no characters are present. 

do 100 i=0,15 

returned_set(i) = 
100 continue 
c 

c Go through the list, setting the bits for each character listed, 
c Note that Pascal numbers the bits right to left, 
c Therefore, a set containing only char(O), that is NULL, has 
c only the least-significant bit set in the last word of the set. 

do 110 i=l,no_of_entries 
c 
c Set the appropriate bit. 

word = 15 - (list(i)/16) 
bit = mod(list(i) ,16) 

returned_set (word) = or ( returned_set (word) ,mask (bit) ) 
110 continue 
c 

return 
end 
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GPR_$EVENT_WAIT 

GPR_$EVENT_WAIT — Waits for an event. 

FORMAT 

unobscured := GPIl_$EVENT_WMT (event_1^pe, event_data, position, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

event_type 

The type of event that occurred, in GPR_$EVENT_T format. Possible 
values are: 

GPR_$KEySTI^KE Input from a keyboard 

GPIi_$BUnDNS Input from mouse or bitpad puck buttons 

GPR_$IiOCATOR Input from a touchpad or mouse 

GPR_$ENTERED_WINDOW Cursor has entered window 

GPR_$LEFT_WI]S1D0W Cursor has left window 

GPR_$LOCAT0R_ST0P Input from a locator has stopped 

GPR_$NO_EVENT No event has occurred 

event_data 

The keystroke or button character associated with the event, or the 
character that identifies the window associated with an entered window 
event. This parameter is not modified for other events. In FORTE^AN, 
this is declared as a character*l variable. 



position 

The position on the screen or within the window at which graphics input 
occurred, in GPR_$POSITION_T format. This is a two-element array of 
2-byte integers. 

unobscured 

A Boolean value that indicates whether or not the window is obscured; a 
false value means that the window is obscured. This value is always 
true unless the program has called GPR_$SET_QBSCURED_OPT and specified 
an option of GPR_$OK_IF_OBS. 

status 

Completion status, in STATUS_$T format. 
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GPR_$EVENT_WAIT 



NOTES 



This routine suspends process execution until the occurrence of an event 
type enabled with the GPIL.$ENABLE_INPUT. If the event type is keystroke 
or button, this routine reports only characters in the enabled keyset. 
Input routines report button events as ASCII characters. See i^pendix 
for keyboard charts showing the ASCII values. 

In direct mode, time-out values do not apply to calls to 
GPR_$EVEISIT_WAIT; that is, GPR_$EVE1SIT_WAIT waits indefinitely. 

The input routines report button events as ASCII characters. "Down" 
transitions range from "a" to "d"; "up" transitions range from "A" to 
"D". The three mouse keys start with (a/A) on the left side. As with 
keystroke events, button events can be selectively enabled by specifying 
a button keyset. 

Unless locator data has been processed since the last event was 
reported, "position" will be the last position given to 
GPR_$SET_ajRSOR_POSITION . 

If locator data is received during this call, and GPIl_$LOCATOR events 
are not enabled, the GPR software will display the arrow cursor and will 
set the keyboard cursor position. 

GPR_$EVENT_WAIT returns an error if the display has not previously been 
acquired. 

This routine may implicitly release the display under two conditions: 

The process must actually suspend execution to wait for an event. 

An event that is not enabled must be handled by the Display 
Manager. 
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GPR_$FORCE_KELEASE 



GPR_$FORCE_RELEASE — Releases the display regardless of how irany times it 

has previously been acquired. 

FORMAT 

GPR_$PORCE_RELEASE (acgui re-count, status) 

i m iJT PARAM ETER S 
None. 

OUTPUT PARAMETERS 

aoqui re-count 

The number of tiroes the display has been acquired. This is a 2-byte 
integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* This call releases the display regardless of how many times 
GPR_$AOQUIRE_DISPLAY has been called. 
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GPK_$GET_EX: 



GPR_$GET_EC — Returns the event c!Ount associated with a graphic event. 

FORMAT 

GPR_$GET_EC (gpr-keyr eventcount-pD inter, status) 

INPUT PARAMETERS 

gpr-key 

The key that specifies which eventcount to obtain, in GPIl_$EC_KEY_T 
format. Currently, this key is always GPIl_$INPUT_EC. 

OUTPUT PARAMETERS 

eventcount-pointer 

A pointer to the eventcount for graphics input, in EC2_$PTR_T format. 

status 

Coir^letion status, in STATUS_$T format. 

NQ TE g 

* GPR_$GET_EC returns the eventcount pointer for the graphics input 
eventcount, which is advanced whenever graphics input may be available. 

* When this eventcount is advanced, it does not guarantee that 
GPR_$COND_EVENT_WAIT will return an event, or that GPR_$EVENT_WAIT will 
not wait. The advance is merely an optimization of a simple polling 
loop that suspends execution of the process until an event might be 
available. 
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GPR_$INIT 



GPR_$INIT — Initializes the graj^ics primitives package. 

FORMAT 

GPR_$INIT (op-mode, unit, size, hi-plane-id, init-bitmap-desc, status) 

INPUT PARAMETERS 

qp-mode 

One of four modes of operation. Graphics primitives routines can 
operate in two bor row-display modes, within a Display Manager window, 
within a frame of a Display Manager pad, or without using the display. 
Use GPR_$DISPLAy_MODE_T format for this parameter. Possible values for 
this parameter are: 

GPR_$BORROW 

GPR_$BORROW_NC 

GPIl_$DIRECr 

GPR_$FRAME 

GPR_$NO_DISPLAy 



unit 



size 



Tliis parameter has three possible meanings, as follows: 

1) The display unit, if the graphics routines are to operate in a 
borrowed display. "Hiis is a 2-byte integer. Currently, the only valid 
display unit number for bor row-display mode is 1. 

2) The stream identifier for the pad, if the gra^iics routines are to 
operate in frame or direct mode. Use STREAM_$ID_T format. Oliis is a 
2-byte integer. 

3) Any value, such as zero, if the graphics routines do not use the 
display. 



The size of the initial bitmap (and the size of the frame, in frame 
mode) , in GPR_$OFFSET_T format. This is a two-element array of 2-byte 
integers. The first element is the bitmap width (and frame width, in 
frame mode) , in raster units; the second element is the bitmap height 
(and frame height, in frame mode) , in raster units. Possible values are 
listed on the next page. 
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GPIl_$INIT 



X 



Bor row-display or direct mode 1 to 1024 1 to 1024 

(limits are reduced to display 

or window size if necessary) : 

Display Manager Frame: 1 to 32768 1 to 32768 

Main Memory Bitmap: 1 to 4096 1 to 4096 

hi-plane-id 

Identifier of the bitmap's highest plane, in GPIL.$PIiANE_T format. Ihis 
is a 2-byte integer. Valid values are: 

For display memory bitnaps: 

for monochromatic displays 

0-3 for color displays in two-board configuration 

0-7 for color displays in three-board configuration 

For main memory bitmaps: 

0-7 for all displays 



OUTPUT PARAMETERS 

init-bitmap-desc 

Descriptor of the initial bitmap, in GPR_$BITMAP_DESC_T format. This is 
a 4-byte integer that uniquely identifies the bitmap. 

status 

Completion status, in STATUS_$T format. 



NOTES 

* See Section 2.2 for information about the modes of (^ration. 

* To use multiple windows, you must call GPR_$INIT for each window. 

* GPR_$BORRaNLNC allows you to allocate a bitmap in display memory without 
setting all the pixels to zero. 

* In GPR_$NO_DISPIiAy mode, the program can manipulate only main memory 
bitmaps. 
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GPR_$INIT 



Size: If a program executes in bor row-display mode or direct mode, the 
size of the initial bitmap can be equal to or smaller than the display. 
See Section 3.3 for details. If the program executes in a frame of a 
Display Manager pad, "size" specifies the size of both the frame and the 
initial bitmap. (In frame mode, the frame and the bitmap must be the 
same size.) If the program does not use the display, GPR_$INIT creates a 
bitmap in main memory. The program specifies the size of this bitmap. 

To use imaging formats, a program must initiate a borrow^display node. 
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GPR_$I^fQ_BITMAP 

GPR_$INQ_BITMAP — Returns the descriptor of the current bititap. 

FORMAT 

GPR_$INQ_BiaMAP (bitmap-desc, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

bitiiiap-desc 

The descriptor of the current bitanap, in GPIL$BITMAP_DESC_T format. 
This is a 4-byte integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To establish a bitmap as the current bitmap, use GPR_$SET_BIIMAP. 
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GPR_$INQ_BI'IMAP_DIMENSIONS 



GPR_$INQ_BnMAP_DIiyiENSIONS — Returns the size and number of planes of a 

bititap. 

FORM AT 

GPIi_$IKJQ_BITMAP_J)IMENSIONS (bitmap-desc, size, hi-plane-id, status) 

INPUT PARAMETERS 

bitmap-desc 

The descriptor of the bitmap, in GPR_$BI'IMAP_DESC_T format. This is a 
4-byte integer. 

OUTPUT PARAMETERS 

size 

Width and height of the bitmap, in GPR_$OFFSET_T format. This is a 
two-element array of 2-byte integers. The first elenent is the bitmap 
width, in raster units; the second element is the bitmap height, in 
raster units. 

hi-plane-id 

The identifier of the bitmap's highest plane, in GPR_$PLANE_T format. 
This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 

NO TE S 

* A program can use the information returned by this call to retrieve the 
actual bitmap size, Tliis could be useful, for example, if the program 
specified a bitnnap size that was too large for the display, causing a 
reduction in bitmap size. 
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GPR_$INQ_BITMAP_POINTER 



GPR_$INQ_BITMAP_POINTER — Returns a pointer to bitmap storage in virtual 

address space. Also returns offset in memory from 
beginning of one scan line to the next. 

FORMAT 

GPR_$INQ_BI1MAP_P0INTER (bitmap-desc, storage-ptr, storage-line-width, status) 

INPUT PARAMETERS 

bitmap-desc 

Descriptor of the bitmap, in GPR_$BI1MAP_DESC_T format. This is a 
4-byte integer. 

OUTPUT PARAMETERS 

storage-ptr 

Start address of bitmap in virtual address space. This is a 4-byte 
integer. In Pascal, storage-ptr is UNIV_PrR. 

storage-line-width 

Number of 16-bit words in virtual memory between the beginning ^of one of 
the bitmap's scan lines and the next. This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* See Section 3.5 for more information about this routine. 

* A program can use the information returned by this call to access 
individual bits. 

* Each scan line (horizontal line of a bitmap) starts on a word boundary. 
"Line-width" gives the offset in memory from the beginning of one scan 
line to the beginning of the next, in units of 16-bit words. 

* When a program uses the "storage-pointer" to access the borrowed 
display, pixels which are white have the value 1 and pixels which are 
black have the value 0, regardless of any calls to GPR_$SET_OOI.OR_MAP. 
Also, if the cursor is active, the cursor pattern appears in the 
biteap. 
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GPR_$INQ_BnMAP_POINTER 



i,j:mxt?vt];o n s 

* A program cannot use this routine on a bitmap which is a Display Manager 
frame. 
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GPIl_$INQ_BM_BIT_OFFSET 



GPR_$INa_BM_BIT_OFFSET — Returns the bit offset that corresponds to the left 

edge of a bititap in virtual address space. 

FORMAT 

GPR_$INQ_BM_BIT_0FFSET (bitmap-desc, offset, status) 

INPUT PARAMETERS 

bitmap-desc 

The descriptor of the bitmap, in GPR_$BITMAP_DESC_T format. This is a 
4-byte integer. 

OUTPUT PARAMETERS 

offset 

The number of bits between a 16-bit word boundary and the left edge of 
the specified bitmap. This is a 2-byte integer in the range zero to 
fifteen. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* Each scan line (horizontal line of a bitmap) starts on a word boundary. 
For all scan lines, this routine returns the number of bits in the most 
significant part of the first word that are not part of the specified 
bitmap. 

* Currently, the offset will be zero for any bitmap other than a 
direct-mode window. 

* For more information about bitmaps, see Section 3.5. 
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GPR_$INQ_CHARACrER_WIDTH 



GPIl_$INQ_CEiARACTEIl_WIDTH — Returns the width of the specified character in 

the specified font. 



FORMAT 

GPIl_$INQ_CHARACTER_WIDTH (font- id, character, width, status) 

INPUT PARAMETERS 

font-id 

Identifier of the text font. This is a 2-byte integer. 

character 

The specified character. This is a CHAR variable. 

OUTPUT PARAMETERS 

width 

The width parameter of the specified character. This is a 2-byte 
integer. Possible values are -127 to 127. 

status 

Completion status, in STATOS_$T format. 



NQ TE g 

* To set a character's width, use GPI^$SET_CHARACTER_WIDTH. 

* The initial character widths are defined in the font file. 

* This routine returns the character width in the local copy of the font. 
Initially, this is a copy of the font file; however, the local copy may 
have been changed. Change in the local copy does not affect the font 
file or the use of the font by other processes. 
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GPIL$I^Q_CDL0RJ1AP 



GPR_$INQ_CX)LOR_MAP — Returns the current color map values. 

FORMAT 

GPR_$INQ_G0L0R_MAP (start-index, n-entries, values, status) 

INPUT PARAMETERS 

start- index 

Index of the first color value entry, in GPR_$PIXEL_VALUE_T format. 
Ihis is a 4-byte integer. 

n-entries 

Number of entries. This is a 2-byte integer. 

OUTPUT PARAMETERS 

values 

Color value entries, in GPR_$COLOR_VECTOR_T format. This is an array of 
4-byte integers. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To set the color map, use GPR_$SET_COLOR_MAP. 



11-51 User Callable Routines 



GPR_$INa_OONFIG 

GPR_$INQ_CDNFIG — Returns the current display configuration. 

FORMAT 

GPR_$INQ_CONFIG (config, status) 

INPUT PARAMETERS 
none 

OUTPUT PARAMETERS 

oonfig 

Display configuration, in GPR_$DISPLiAY_(XasiFIG_T format. The returned 
value for each display type is listed belcw: 

Display Type Returned Value 

monochromatic portrait GPR_$BW_800xl024 

monochromatic landscape GPI^$BW_1024x800. 

color 1024 X 1024 (DN600) 2-board configuration GPR_$COLOR_1024xl024x4 

color 1024 X 1024, 3-borad configuration GPIi_$COLOR_1024xl024x8 



status 

Completion status, in STATUS_$T format. 
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GPIl_$INQ_GONSTRAINTS 



GPR_$INQ_OONSTRAINTS — Returns the clipping window and plane mask used for 

the current bitmap. 

FORMAT 

GPR_$INQ_CDNSTE?AINTS (window, active, plane-irask, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

window 

Hie clipping window, in GPiL.$WlNDOWLT format. This is a two-elenent 
array of two-element arrays. (In FORTRAN, use a two-dimensional array.) 

The first element of GPR_$WINDOW_T specifies the window origin (top left 
corner coordinates) , in GPIL.$POSITION_T format. This is a two-element 
array of 2-byte integers. The first element is the origin's 
x-coordinate; the second element is the y-coordinate. Coordinate values 
must be within the bitmap limits. 

Ihe second element of GPIl_$WINDOWLT specifies the window width and 
height, in GPR_$OFFSET_T format. This is a two-element array of 2-byte 
integers. The first element is the window width, in raster units; the 
second element is the window height, in raster units, width and height 
values, when added to the corresponding bitmap origin, must be within 
the bitmap limits. 

active 

Boolean (logical) value which specifies whether the clip window is 
enabled. If the value is false, the clip window is disabled; if the 
value is true, the clip window is enabled. 

plane-mask 

The plane mask, which specifies the active bitmap plane (s), in 
GPR_$MASK_T format. This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 



NOTES 



To establish a new clipping window for the current bitmap, use 

GPR_$SET_CLIP_WINDCW. To enable the new clipping window, use 

GPR_$SET_CLIPPING_ACTIVE. Tto establish a plane mask, use 
GPR_$SET_PLANE_MASK. 
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GPR_$INQ_OOORDINATELORIGIN 



GPR_$INQ_OOORDINATELORIGIN — Returns the x- and y-off sets added to all x- 

and y-coordinates used as input to move, line 
drawing, and BLT operations on the current 
bitmap. 

FORMAT 

GPIl_$INQ_00ORDINATE_ORIGIN (origin, status) 

OUTPUT PARJ^METERS 

origin 

The current coordinate origin for the bitmap, in GPR_$POSITION_T 
format. This is a two-element array of 2-byte integers. The first 
element is the origin's x-coordinate; the second element is the 
y~coordinate. 

status 

Completion status, in STATUS_$T format. 



NOTES 

* To set a new coordinate origin, use GPR_$SET_<X)ORDINATELORIGIN. 
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GPKJ$WQ_CP 

GPR_$INQ_CP — Returns the current position in the current bitmap. 

F O R MA T 

GPR_$INQ_CP (x, y, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 
X 

The x-coordinate of the current position, in GPR_$COORDINATE_T format. 
This is a 2-byte integer. 

y 

The y-coordinate of the current position, in GPIl_$CXX)RDINATE_T format, 
•fliis is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 
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GPR_$INQ_ajRSOR 



GPR_$INQ_ajRSOR — Returns infornation about the cursor. 

FORMAT 

GPR_$I^fQ_CURSOR (curs-pat, curs- raster-op, active, position, origin, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

cursor-pat 

Identifier of the cursor pattern bitmap, in GPR_$BITMAP_DESC_T format. 
Ihis is a 4-byte integer. 

cursor-raster-op 

Cursor raster operation code, in GPIL.$RASTER_OP_ARRAY_T format. This is 
an eight-elonent array containing eight 2-byte integers. Currently, the 
value is 3. (The operation assigns all source values to the new 
destination) . 

active 

A Boolean (logical) value which indicates whether the cursor is 
displayed. Ihe parameter is set to true if the cursor is displayed; it 
is set to false if the cursor is not displayed. 

position 

The cursor's current position on the screen, in GPIL_$P0SITI01L.T format. 
This is a two-element array of 2-byte integers. T3ie first element is 
the cursor position's x-coordinate; the second element is the 
y-coordinate. 

origin 

The pixel currently set as the cursor origin, in GPI^$P0SITI0N_T 
format. Oliis is a two-element array of 2-byte integers. The first 
element is the pixel's cursor- relative x-coordinate; the second element 
is the pixel's cursor-relative y-coordinate. 

status 

Completion status, in STATUS_$T format. 
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NOTES 



* Cursor position: If a program calls this routine when in bor row-display 
mode, the x- and y-coordinates represent an absolute position on the 
screen. If a program calls this routine when the cursor is inside a 
frame of a display nanager pad, the x- and y-coordinates are relative to 
the top left corner of the frame. 

* To alter the cursor, use one of the following: 
GPR_$SET_CURSOIL.PATTERN 
GPR_$SET_ajRSOR_ACTIVE 
GPR_$SET_ajRSOR_POSITION 
GPi^$SET_ajRSOR_ORIGIN 

* Currently, a program can not alter the cursor raster operation. 



11-57 User Callable Routines 



GPR_$INC1_DRAW_VALUE 



GPR_$INQ_DRAW_VALUE — Returns the color/ intensity value used for drawing 

lines. 



GPIi_$INQ_DRAW_VALUE (index, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

index 

The color map index that indicates the current color/intensity value 
used for drawing lines, in GPR_$PIXEl4_VALUE_T format. This is a 4-byte 
integer. Valid values are: 

0-1 for monochromatic displays 

0-15 for color displays in 4-bit pixel format 

0-255 for color displays in 8-bit or 24-bit pixel format 

-1 for all displays. This specifies that the background is 

transparent; that is, the old values of the pixels are not 
changed. 
-2 for all displays. This specifies using the color/ intensity 
value of the bitmap background as the line drawing value. 
For borrowed displays and memory bitmaps, the fill 
background is always zero. For Display Manager frames, this 
is the pixel value in use for the window background. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To set a new draw value, use GPIL$SET_DRAW_VALUE. 
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GPIl_$INQ_FIIIj_BACKGiaJND_VALUE 



GPR_$INa-FILL_BACKGROUMD_VALUE — Returns the cx)lor/ intensity value of the 

background used for tile fills. 

FORMAT 

GPR_$INQ_FILL_BACKGROUND_VALUE (index, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

index 

The color map index that indicates the current color/ intensity value 
used for tile fills, in GPR_$PIXEIt_VALUE_T format. This is a 4-byte 
integer. Valid values are: 

0-1 for monochromatic displays 

0-15 for color displays in 4-bit pixel format 

0-255 for color displays in 8-bit or 24-bit pixel format 

-1 for all displays. This specifies that the background is 

transparent; that is, the old values of the pixels are not 
changed. 
-2 for all displays. Ihis specifies using the color/ intensity 
value of the bitmap background as the tile fill background. 
For borrowed displays and memory bitmaps, the fill 
background is always zero. For Display Manager frames, this 
is the pixel value in use for the window background. 

status 

Completion status, in STATUS_$T format. 



NPTEg 

* To set a new background value, use GPR_$SET_FILL_BACKGRDUND_VALUE. 
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GPR_$INQ_FILL_PATTERN 

GPIL.$INQ_FIIiL_PATrERN — Returns the fill pattern for the current bitmap. 

GPR_$INQ_FILL_PATTERN (pattern, scale, status) 

INPUT PARAMETERS 
None. 

OUT PUT PARM^TERg 

pattern 

The descriptor of the bitmap containing the fill pattern, in 
GPR_$BITMAP_DESC_T format. This is a 4-byte integer. 

scale 

The number of times each bit in this pattern is to be replicated before 
proceeding to the next bit in the pattern. This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 



NOT E g 

* To set a new fill pattern for the current bitmap, use 
GPR_$SET_FILL_PATTERN. 

* Currently, the tile pattern must be stored in a bitmap that is 32x32 
pixels by n planes. Uie scale factor must be one. Any other pattern 
size or scale value results in an error. 

* With a one-plane bitmap as the pattern, the pixel values used are those 
set by GPI^$SET_Fim_VALUE and GPR_$SET_FILL_BACKGROUND_VALUE. Pixels 
corresponding to "1" bits of the pattern are drawn in the fill value: 
pixels corresponding to "0" bits of the pattern are drawn in the fill 
background value. 
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GPI^$INQ_FILLVALUE 



GPR_$INQ_FILl4_VALUE — Returns the color/ intensity value used to fill 

circles, rectangles, triangles, and trapezoids. 



FORMAT 

GPR_$INQ_FII1,_VALUE (index, status) 

INPUT PARAMETERS 
None, 

OUTPUT PARAMETERS 

index 

The color map index that indicates the current color/intensity fill 
value, in GPR_$PIXEl4_VALUE_T format. This is a 4-byte integer. Valid 
values are: 

0-1 for monochromatic displays 

0-15 for color displays in 4-bit pixel format 

0-255 for color displays in 8-bit or 24-bit pixel format 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To set a new fill value, use GPR_$SET_FILL_VALUE. 
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GPR_$I^Q_HORIZONTArt_SPACING 



GPR_$I^fQ_HORIZCM^AI^_SPACING — Returns the parameter for the width of 

spacing between displayed characters for the 
specified font. 

FORMAT 

GPR_$INQ_HORIZONTAL_SPACING (font-id, horizontal-spacing, status) 

INPUT PARAMETERS 

font-id 

Identifier of the text font. This is a 2-byte integer. 

OUTPUT PARAMETERS 

horizontal-spacing 

The parameter for horizontal spacing of the specified font. This is a 
2-byte integer. Possible values are -127 to 127. 

status 

Completion status, in STATUS_$T format. 



NOTES 

* Use GPR_$SET_HORIZC»ITAL_SPACING to set the width of spacing for a 
font. 

* The initial width of horizontal spacing is defined in the font file. 

* This routine returns the horizontal spacing in the local copy of the 
font. Initially, this is a copy of the font file; however, the local 
copy may have been changed. Change in the local copy does not affect 
the font file or the use of the font by other processes. 
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GPR_$I^Q_IMAGING_FORMAT 

GPR_$INQ_IMAGING_fORMAT -— Returns the current inaging format. 

FOmh T 

GPR_$INQ_IMGINGJFORMAT (format, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

format 

Imaging format in GPR_$IMAGING_FORMAT_T configuration. If you are using 
an interactive format, the returned value is GPR_$INTERACTIVE. 

If you are using the imaging 8-bit pixel format on a two-board 
configuration, the returned value is GPR_$IMAGING_1024xl024x8. If you 
are using the imaging 24-bit pixel format, the returned value is 
GPR_$IMAGING_512x512x24 . 

status 

Completion status, in STATUS_$T format. 

* See Section 2.3 for more information about imaging formats. 
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GPR_$INa_LINE_PATTERN 



GPR_$INQ_LINE_PATTERN — Returns the pattern used in drawing lines. 

FORMAT 

GPR_$INQ_LIME_PATTERN (repeat, pattern, length, status) 

INPUT PARAMETERS 
None, 

OOTPUT PARAMETERS 

repeat 

The replication factor for each bit in the pattern. This is a 2-byte 
integer. 

pattern 

The bit pattern, left justified, in GPR_$LINE_PATTERN_T format. This 
is a four-elonent array of 2-byte integers. 

length 

Ihe length of the pattern in bits. This is a 2-byte integer in the 
range of to 64. 

status 

Goir^letion status, in STATUS_$T format. 



NOTES 

* GPR_$INQ_LINE_PATTERN returns the current line pattern set explicitly 
with GPR_$SET_LINE_PA1TERN or set inplicitly with GPil_$SET_LINESTYLE. 

* Use GPR_$SET_LINE_PATTERN to specify a new line pattern. You can also 
use GPR_$SET_LINESTYLE to set a line pattern within the limits of the 
parameter GRP_$DCXnED. 
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GPK_$I1SJQ_LINESTYLE 



GPR_$INQj:iINESTYLE — Returns information about the current line-style. 

FORMAT 

GPR_$INQ_LINESTYLE (style, scale, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

style 

The style of line, in GPR_$LINESTYLE_T format. Possible values are 
GPR_$SOLID and GPR_$DOTTED. This is a 2-byte integer. 

scale 

The scale factor for dashes if the style parameter is GPR_$DOTrED. This 
is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 

* When the line-style attribute is GPR_$DOTTED, lines are drawn in 
dashes. The scale factor determines the number of pixels in each dash 
and in each space between the dashes. 

* To set the line-style attribute, use GPR_$SET_LINESTXLE. 
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GER_$INQ_RASTEP^OPS 



GER_$INQ_RASTER_OPS — Returns the raster operations for the current 

bitmap. 

F QTOyr 

GH^$INQ_RASTEIL.OPS (raster-op, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

raster-op 

Raster operation codes, in GPR_$RASTER_OP_ARRA!CT format. This is an 
eight-elonent array of 2-byte integers. Each elenent corresponds to the 
raster operation for a single plane of the bitmap. Possible raster op 
values are zero through fifteen. 

status 

Completion status, in STATOS_$T format. 

I^QTEg 

* See Table 3-1 for a listing of the raster operation codes and their 
functions. 

* To set a new raster operation for tlrie current bitmap, use 
GER_$SET_RASTER_OP. 
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GPR_$INQ_SPACE_SIZE 



GPR_$INQ_SPACE_SIZE — Returns the width of the space to be displayed when a 

character requested is not in the specified font. 

FORMAT 

GPR_$IKfQ_SPACE_SIZE (font- id, space-size, status) 

INPUT PARAMETERS 

font-id 

Identifier of the text font. This is a 2-byte integer. 

OUTPUT PARAMETERS 

space-size 

The space size of the specified font. T3iis is a 2-byte integer. 
Possible values are -127 to 127. 

status 

Completion status, in STATUS_$T format. 



NOTES 

* To set a font's space size, use GPR_$SET_SPACE_SIZE. 

* The initial space size is defined in the font file. 

* The space size is the number of pixels to skip in the horizontal 
direction when a character that is not in the font is written. 



11-67 User Callable Routines 



GHL.$INQ_TEXT 



GPR_$I1SKI_TEXT — Returns the text font and text path used for the current 
bitmap. 

FORMAT 

GER_$INQ_TEXT (font- id, path, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

font-id 

Identifier of the text font used for the current bitmap. This is a 
2-byte integer. 

path 

The direction of movement fron one text character position to the next 
in the current bitmap, in GPPs^$DIRECriON_T format. Possible values are 
GPR_$UP, GHL_$DOWN, GPR_$LEPr, and GHl_$RIGHT. 

status 

Completion status, in STATOS_$T format. 

NOTES 

* To set a new text font for the current bitmap, use GPE^$SET_TEXT_POWr. 
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GPIi_$INQ_lEXT_EXTEI«? 



GPR_$INQ_TEXT_EXTEINT ~ Returns the x- and y-offsets a string spans when 

written by GPR_$'IEXT. 



FORMAT 

GPIi_$INQ_TEXT_EXaENT (string, string-length, size, status) 

INPUT PARAMETERS 

String 

A string, in GPR_$STRING_T format. Tliis is an array of characters. 

string-length 

Number of characters in the string. This is a 2-byte integer. The 
maximum value is 256. 

OUTPUT PARAMETERS 

size 

Width and height of the area the written string would occupy, in 
GPR_$OFFSET_T format. This is a two-elonent array of 2-byte integers. 
The first elenent is the width (the x-off set) ; the second element is the 
height (the y-of f set) . 

status 

Completion status, in STATUS_$T format. 

NOTES 

* When the text path is GPR_$RIGHT or GPI^$LEFT, the width is the 
x-off set. When the text path is GPIl_$UP or GPR_$DCWN, the height is 
the y-of f set. 

* See GPR_$SET_TEXT_PA1H for use of GPR_$RIGHT, GPR_$LEFT, GPIl_$UP, and 
GPR_$DOWN. 

* Figure 11-1 shows two examples of the extent of text in relation to 
offsets. For horizontal text, use GPIi_$RIGHT with GPI^$SET_'IEXT_PA'rH. 
For rotated text, use GPR_$UP with GPIl_$SET_TEXT_PATH. 
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lA brown fox jumped over the fencej 
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Figure 11-1. Height and Widtii for Horizontal and Rotated Text 
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GPR_$INQ_TEXT_OFFSET 



GPR_$IlSfQ_TEXT_OFFSET — Returns the x- and y-off sets from the top left pixel 

of a string to to the origin of the string's first 
character. This routine also returns the x- or 
y-offset to the pixel which is the new current 
position after the text is written with GPR_$TEXT. 

FORMAT 

GPR_$INQ_TEXT_OFFSET (string, string-length, start, xy-end, status) 

INPUT PARAMETERS 

string 

A string, in GPR_$STRING_T format. Ihis is an array of characters. 

string-length 

Number of characters in the string. Ihis is a 2-byte integer. The 
maximum value is 256. 

OUTPUT PARAMETERS 

start 

X- and y-off sets from the top left pixel of the string to the origin of 
its first character, in GPR_$OFFSET_T format. This is a two-elonent 
array of 2-byte integers. The first element is the x-offset; the second 
element is the y-off set. 

3^-end 

The X- or Y-offset from the top left pixel of the string to the pixel 
that will be the new current position after the string is written with 
GPR_$TEXT. This is the X-offset when the text path is specified as 
GPR_$RIGHT or GPR_$LEFT. This is the Y-offset when the text path is 
specified as GPR_$UP or GPR_$DOWN. This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 
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NOTES 



A program can use the information derived from the "start" output 
parameter to set the current position to the character origin, rather 
than the top left corner of the string, before writing the string with 
GPIl_$TEXT. 

When the text path is GPIl_$RIGHT or GPil_$LEFT, the offset is to the 
X-axis. When the text path is GPIl_$UP or GPIL_$DOWN, the offset is to 
the y-axis. 

See GPR_$SET_TEXT.PATH for use of GPIl_$RIGHT, GPIl.$LEFT, GPIL$UP, and 
GPR_$DOWN. 

Figure 11-2 shows an example of text offsets, after using GPIl_$RIGHT and 
GPR_$UP with GPIL.$SET_'IEXT_PATH. 
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Top left pixel of 
character string 



Origin of first 
character 




Current Position 
upon completion 

brown fox jumped over the tence^ r^^ of GPR — $TEXT and 

' ^ ^ GPR_$SET^TEXT_PATH 

with GPR_$RIGHT 



Top left pixel of character string 




Current position upon completion of 
GPR_$TEXT and GPR_$TEXT_PATH with 
GPR_$UP 



Text path is up from origin, 
letters reading up 



Origin of first character 



Figure 11-2. Text Offsets 
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GPR_$INQ_TEXT_PA1H 

GPR_$INQ_TEXT_PA1H — Returns the direction for writing a line of text. 

FORMAT 

GPR_$INQ_TEXT_PATH (direction, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

direction 

Direction for writing text, in GPR_$DIRECTION_T format. Possible values 
are GPR_$UPr GPR_$DOWN, GPR_$LEFT, and GPR^$RIGHT. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To set the current text path, use GPR_$SET_TEXT_PA1H. 
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GPR_$INQ_'IEXT_VALUES — Returns the current values of text and text 

background color/ intensity value used in the current 
bitmap. 

FORMAT 

GPR_$INQ_TEXT_VALUES (text-value, text-bkgd-value, status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

text-value 

A color map index that indicates the text color/ intensity value, in 
GPR_$PIXEL_VALUE_T format. 

text-bkgd-value 

A color map index that indicates the text background color/ intensity 
value, in GPR_$PIXEL_T format. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To establish the text color/ intensity value, use GPR_$SET_TEXT_VALUE. 
To establish the text background color/ intensity value, use 
GPR_$SET_1EXT_BACKGR0UND_VALUE. 
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GPR_$INQ_VIS_LIST — Returns a list of the visible sections of an obscured 

window. 



FORMAT 

GPI^$INQ_VIS_LIST (slots-available, slots-total, vis-list, status) 

INPUT PARAMETERS 

slots-available 

The size of the array of visible window sections. This is a 2-byte 
integer, which is the naximum number of visible rectangles that can be 
returned. If you want to list all existing sections, you must specify a 
number that is greater than or equal to the number returned in the 
slots- total argument. 

OUTPUT PARAMETERS 

slots-total 

The number of existing visible rectangles. This is a 2-byte integer. 
If this value is greater than the slots-available parameter, then only 
the number of rectangles specified in slots-available is returned. 

vis-list 

The list of visible window sections. This is an array in GPR_$WINDavLT 
format. GPR_^INDCW_T format consists of a two-element array of 
two-element arrays. (In FORTE^^, you can use a two-dimensional array.) 

The first element of GPR_$WINDCW_T specifies the window section's base 
relative to the top left corner of the window, in GPR_$POSITION_T 
format. This is a two-element array of 2-byte integers. The first 
elonent is the x-coordinate of the base; the second is the 
y-coordinate. 

The second element of GPR_^I1SID0W_T specifies the section's size, in 
GPR_$OFFSET_T format. This is a two-elonent array of 2-byte integers. 
The first elonent is the section width in raster units; the second 
element is the section height. 

There is no set limit to the number of visible regions that may be 
returned. 

status 

Completion status, in STATUS_$T format. 
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NOTES 



* If the display has been acquired but the target window is obscured, 
programs can call GPR_$INQ_VIS_LIST to locate any visible sections of 
the window. 

* If the target window is visible, this routine returns a base of (0,0) 
and the size of the entire window. 

* If the window is obscured, the application should call 
GPR_$SET_CLIP_WINDOW once for each rectangle returned by 
GPR_$INQ_VIS_LIST before making calls to drawing routines. Clijping is 
to rectangles only. The GPR software will not perform clipping 
automatically. 

* GPR_$INQ_VIS_LIST implicitly releases and reacquires the display in 
order to communicate with the Display Manager. 
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GPR_$INQ_WINDCIWLID — Returns the character that identifies the current 

bitmap's window. 

FORMAT 

GPR_$INQ_WINDCIWLID (character, status) 

INPUT PARAMETERS 
none 

OUTPUT PARAMETERS 

character 

The character that identifies the current bitmap's window. 

status 

Completion status, in STATUS_$T format. 

NQTEg 

* This character is returned by GPH_$EVENT_WAIT and GPR_$COND_EVENT_WAIT 
when they return GPR_$ENTERED_WINDOW events. The character indicates 
which window was entered. 

* The character 'A' is the default value of the window identification for 
all windows. 
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GPR_$LINE — Draws a line from the current position to the given position, 
then updates the current position to the given position. 



FORMAT 

GPR_$LINE (x,y, status) 

INPUT PARAMETERS 
X 

The x-coordinate, which designates the end point of the line and then 
becomes the current x-coordinate. Use GPR_$COORDINATE_T format. Ihis is 
a 2-byte integer. Its values must be within the bitmap limits, unless 
clipping is enabled. 

y 

The y-coordinate, which designates the end point of the line and then 
becomes the current y-coordinate. Use GPR_$CXX)RDINATE_T format. Ihis 
is a 2-byte integer. Its values must be within the bitmap limits, unless 
clipping is enabled. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* The given coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
position is the destination of the line drawn. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 

* After the line has been drawn, its end point becomes the current 
position. 

* To set a new position without drawing a line, use GPR_$MOVE. 
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GPR_$LOAD.JX^T_FILE — Loads a font from a file into the display's font 

storage area, 

FORMAT 

GPR_$LOAD_FONT_FILE (pathname, pathname-length, font-id, status) 

INPUT PARAMETERS 

pathname 

Pathname of the file containing the font, in NAME_$PNAME_T format. This 
is a character string. 

pathname-length 

Number of characters in font file pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

font-id 

Font identifier. This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 

NOTES 

* Use the font-id returned from this file as input for 
GPR_$SET_TEXT_FC»IT. 

* To unload fonts loaded with this routine, use GPIL.$UNLQAD_FONT_FILE. 
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GPIl_$MOVE 



GPR_$MOVE — Changes the current position. 

FORMAT 

GPR_$MOVE (x, y, status) 

INPUT PARAMETERS 

X 

The x-coordinate, which becomes the current x-coordinate, in 
GPR_$COORDINATE_T format. This is a 2-byte integer. Its values must be 
within bitmap limits, unless clipping is enabled. 

The y-coordinate, which becomes the current y-coordinate, in 
GPR_$COORDINATE_T format. This is a 2-byte integer. Its values must be 
within bitmap limits, unless clipping is enabled. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* The current position is the starting point for any line drawing and text 
operations. 

* GPR_$MOVE does not draw any lines. 

* See Section 6.1 for more information about the current position and the 
move routine. 

* The given coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
position is the destination of the move operation. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPR_$MULTILINE 

GPR_$MULTILI^E — Draws a series of disconnected lines. 

FORMAT 

GPR_$MULTILINE (x, y, npositions, status) 

INPUT PARAMETERS 
X 

List of the x-coordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$COORDINATE_ARRAY_T 
format is an example of such an array. The values must be within the 
bitmap limits, unless clipping is enabled. 

y 

List of the y-coordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$COORDINAIE_ARRAY_T 
format is an example of such an array The values must be within the 
bitmap limits, unless clipping is enabled. 

npositions 

Number of coordinate positions. Ihis is a 2-byte integer in the range 
1-32767. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 



* GPR_$MULTILINE alternately moves to a new position and draws lines: it 
moves to the first given position, draws a line from the first to the 
second given position, moves to the third position, etc. After the last 
line has been drawn or the last move has been made, the endpoint becomes 
the current position. 

* The given coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
position is the destination of the multiline drawn. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitinap limits results in an error. 
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GPR_$MULTITKAPEZOID — Draws and fills a list of trapezoids in the current 

bitmap, 

FORMAT 

GPR_$MULTITRAPEZOID (trapezoid-list, trapezoid-number, status) 

INPUT PARAMETERS 

trapezoid-list 

The trapezoids to fill. This is an array of one or more trapezoids in 
GPR_$TRAP_T format, a two-elonent array in GPR_$HORIZ_SEG_T format. The 
first element is the top horizontal segment of the trapezoid; the sec»nd 
element is the bottom horizontal segment. 

trapezoid-number 

The number of trapezoids to fill. This is a 2-byte integer. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* GPR_$MULTITRAPEZ0ID fills in a list of trapezoids with the 
color/ intensity value specified with GPR_$SET_FIIIi_VALUE. 

* To retrieve the current fill value, use GPI^$INQ_FIIiL_VALUE. 
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GPR_$OE®I_BI'IMAP_FILE — Opens a file for external storage of a bitmap. 

FORMAT 

GPIL.$OPEN_BI'IMAP_FILE (access, filename, name-size, version, size, groups, 

group-headers, attributes, bitmap, created, status) 

access 

One of four ways to access external bitmap objects, in 
GPR_$ACCESS_MDDE_T format. Possible values for this parameter are: 

GPR_$CREATE 
GPR_$UPDATE 
GPIl_$WRITE 
GPIl_$READONLY 

filename 

•The pathname of the bitmap file, in NAME_$PNAME_T format. 

name-size 

The length of the file name. Ihis is a 2-byte integer. 

version 

The version number on the header of the external bitmap file, in 
GPR_$VERSION_T format. This is a two-elonent array of two 2-byte 
integers: a major version number and a minor version number. Currently, 
version is not used and is always returned as major version 1, minor 
version 1. 

size 

Bitmap width and height, in GPR_$OFFSET_T format. This is a two-elonent 
array of 2-byte integers. The first element is bitmap width, in raster 
units; the second element is the bitmap height, in raster units. 
Possible values for x are 1-4096; possible values for y are 1-4096. 

groups 

The number of groups in external bitmaps. This is a 2-byte integer. 
Possible values are 1 . . (GPil_$MA5C_BMF_GRDUP +1 ) . Currently, groups are 
not used; this value must be 1. 

group-headers 

Descriptors of the external bitmap group headers, in 
GPR_$BMF_GROUP_HEADER_ARRAY_T format. This is an array 
[O..GPR_$MAX_BMF_GROUP] of GPI^$BMF_GROUP_HEADER_T. Possible values 
for fields in a group header are the following. Alignment constraints 
are included: 
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N_SECTS 2-byte integer, 1..8 

PIXEL_SIZE 2-byte integer 

Currently, this value must be 1. 

ALLOCATED_SIZE 2-byte integer 

Currently, this value must be 1. 

BYTES_PEIL.LI]SE 2-byte integer 

This value must be a multiple of 4 
This value is usually specified as 0. 

BYTES_PER_SECT 4-byte integer 

This value must be either rounded up to a page 

boundary, or for small bitmaps rounded 

up to the next largest binary submultiple 

of a page, for example, one-half, 

one-fourth, or one-eighth. 

One page equals 1024 bytes. 

This value is usually specified as 0. 

STORAGE_OFFSET UNIV_PTR format 

attribs 

The attributes which the bitmap will use, in GPIl_$A'ITRIBUTE_DESC_T 
format. This is a 4-byte integer. 

OUTPUT PARAMETERS 

bitmap 

Descriptor of the bitmap, in GPR_$BI™ap_DESC_T format. This is a 
4-byte integer. 

created 

Boolean (logical) value which specifies whether the bitmap file was 
created. If the value is true, the file was created. 

status 

Conpletion status, in STATUS_$T format. 



NPTES 

* See Chapter 10 for sample programs that use GPR_$OPEN_BI'nyiAP_FILE. 

* Currently, a section is equivalent to a bit plane. N_SECTS iray include 
up to eight bit planes. 

* For ALLCX:atED_SIZE, ByTES_PEIl_LINE and BYTES_PEI^SECT, you can specify 
values as 0, and the GPR package will calculate and return the 
appropriate values. 

* BYTES_PER_SECT is not necessarily a multiple of BYTES_PEIL.LINE. This 
means that GPR will leave unused space at the end of one section to 
satisfy alignment constraints. The result is that the next section 
starts on an alignment boundary, which is normally a page boundary. 
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* The access parameter specifies one of four ways to use external 
bitmaps. As shown in the table below, the value given for this 
parameter determines whether four other parameters are input (IN) or 
output (OUT) . The values for these parameters are used to validate your 
input with GPIL$CREATE and GPR_$UPDATE. 



GPR_$CREATE GPR_$UPDATE GPR_$WK[TE GPIl_$READONLY 
file exists 
no yes 



version, 
size, 
groups, 
group- 
headers 




* GPR_$CREATE indicates that you want a new external bitmap file. 
GPIl_$UPDATE means that you want to create a new file or overwrite an 
existing one. 

* When you specify GPR_CREATE as the access parameter and you specify a 
file name that already exists, the file is superseded only if it is a 
bitmap file. If the file is not a bitmap file, you get the error 
message NA^E_$ALREADY_EXISTS. 

* Attributes are not stored with the bitmap. You assign attributes when 
you open the bitmap file. See the routines 
GPR_$ALLOCATE_AITRIBU'IE_BLOCK and GPIl_$ALLOCATE_BITMAP. 

* FORTRAN programmers can use the following equivalences: 



Parameter 

Integer*2 
Integer*4 

Equivalence 

N_SECTS 

PIXEl4_SIZE 

ALLOCATED_SIZE 

BYTES_HSR_LINE 

BYTES_PER_SECT 

STORAGEOFFSET 



(n_groups =1) 

header s2 ( 8 , n_groups ) 
headers4 ( 4 , n_groups ) 

headers2 (1,1), headers4 (1,1) 

header s2(l,n) 
headers2(2,n) 
header s2( 3, n) 
headers2(4fn) 
header s4( 3, n) 
headers4(4fn) 



* Figure 11-3 is a global view of one group. 
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BYTES PER LINE 



GPI^$OPEN_BITMAP_FILE 



BYTES 

PER 

SECTION 



^ 



S 



^ SECTION 

I 



^ 
^ 



SECTION 1 



ETC. 



WITHIN A LINE 



WWW 
LWV 



< PIXEL SIZE> 
< ALLOCATED SIZE > 



BOTH IN BITS 



Figure 11-3. View of One Group 
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GPR_$PGON_POLYLIME — Defines a series of line segments forming part of a 

polygon boundary. 

FORMAT 

GPR_$PG(^_POLYLn© (x, y, npositions, status) 

INPUT PARAMETERS 

X 

List of the x-cx)ordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$COORDINATE_ARRAy_T 
format is an example of such an array. The values must be within the 
bitmap limits, unless clipping is enabled. 

y 

List of the y~ooordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPI^$COORDINATE_ARRAY_T 
format is an example of such an array. The values must be within the 
bitmap limits, unless clipping is enabled. 

npositions 

Number of coordinate positions. Tliis is a 2-byte integer in the range 
1-32767. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 



GPR_$PGON_POLYLINE defines a series of line segments that comprise part 
of a polygon to be filled in by either (1) GPIl_$CLOSE_FILL_PG0N or by 
(2) GPR_$CLOSE_RETURfL.PGC»^ and GPR_$MULTITRAPEZOID. The lines are not 
drawn on the screen until the polygon is filled in by either routines 
(1) or (2) above. To draw a series of connected lines without filling 
the resulting figure, use GPIl_$POLYLINE. 

GPR_$PGON_POLYLINE must be called only when the line segments of a 
polygon are being defined; see the routine GPR_$START_PGasi for more 
information. 

When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPR_$PIXEL_BLT — Performs a pixel block transfer from any bitnap to the 

current bitmap. 

FORMAT 

GPR_$PIXEL_BLT (source-bitinap-desc, source-window, dest-origin, status) 

INPUT PARAMETERS 

source-bitmap-desc 

Descriptor of the source bitmap which contains the source window to be 
transferred, in GPR_$BnMAP_DESC_T format. This is a 4-byte integer, 

source-window 

Rectangular section of the bitmap from which to transfer pixels, in 
GPR_$WINDCIK_T format. This is a two-elonent array of two-element 
arrays. (In FORTI^AN, you can use a two-dimensional array.) 

The first element of GPR_$WINDCW_T specifies the origin of the window 
(top-left corner) , in GPR_$P0SITI01L.T format. This is a two-elonent 
array of 2-byte integers. The first element is the origin's 
x-coordinate; the second elanent is the y-coordinate. Coordinate values 
must be within the limits of the source bitmap. 

The second elotient of GPR_$WINDCW_T specifies the window width and 
height, in GPR_$OFFSET_T format. Ihis is a two-element array of 
two-byte integers. The first element is the window width, in raster 
units; the second element is the window height, in raster units. 

dest-origin 

Start position (top left coordinate position) of the destination 
rectangle, in GPR_$POSITION_T format. Ihis is a two-element array of 
2-byte integers. The first element is the origin's x-coordinate; the 
second element is the y-coordinate. Coordinate values must be within 
the limits of the current bitmap, unless clipping is enabled. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 

* Use GPR_$SET_BnMAP to establish the current bitmap for this routine. 

* Both the source and destination bitmaps can be in either display memory 
or main memory. 
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* The source window origin is added to the coordinate origin for the 
source bitmap, and the result is the actual origin of the source 
rectangle for the BLT. Similarly, the destination origin is added to 
the coordinate origin for the current bitmap, and the result is the 
actual origin of the destination rectangle for the BLT. 

* If the source bitmap is a Display Manager frame, the only allowed raster 
op codes are 0, 5, A, and F. These are the raster operations in which 
the source plays no role. 

* If a rectangle is transferred by a BLT to a Display Manager frame and 
the frame is refreshed for any reason, the BLT is re-executed. 
Therefore, if the information in the source bitmap has changed, the 
appearance of the frame changes accordingly. 
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GPR_$POLYLI^E — Draws a series of connected lines. 

FORMAT 

GPR_$POLYLI^E (x, y, npositions, status) 

INPUT PARAMETERS 
X 

List of the x-coordinates of all the successive positions. Tliis is a 
one-dimensional array of 2-byte integers. GPIl_$CX)ORDINATE_ARRAY_T 
format is an example of such an array. 'She values must be within the 
bitmap limits, unless clipping is enabled. 

y 

List of the y-coordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$COORDINATE_ARRAY_T 
format is an example of such an array. The values must be within the 
bitmap limits, unless clipping is enabled. 

npositions 

Number of coordinate positions. This is a 2-byte integer in the range 
1-32767. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* GPR_$POLYLINE draws a series of connected lines: it starts from the 
current position, draws to the first given position, then sets the 
current position to the first given position. This is repeated for all 
given positions. 

* The given coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
position is the destination of the polyline drawn. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 

* See Section 6.2 for more information about drawing polylines. 
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GPIl_$READ_PIXELS 



Reads the pixel values from a window of the 
bitmap and stores the values in a pixel array. 



current 



FORMAT 

GPR_$READ_PIXELS (source-window, pixel-array, status) 



INPUT PARAMETERS 

source-window 

Rectangular section of the current bitmap 
values (color/ intensity) , in GPIL.$WINDCXV_T 
two-element array of two-element arrays, 
two-dimensional array.) 



from which to read pixel 

format, This is a 

(In FORTE^AN, you can use a 



The first element of GPIl_$WINDCW_T specifies the window origin (the top 
left corner coordinates) , in GPII_$P0SITI0N_T format. This is a 
two-element array of 2-byte integers. The first element is the origin's 
x-coordinate; the second element is the y-coordinate. Coordinate values 
must be within bitmap limits. 

The second element of GPR_$WINDOW_T specifies the window width and 
height, in GPR_$OFFSET_T format. This is a two-element array of 2-byte 
integers. The first element is the window width, in raster units; the 
second element is the window height, in raster units. Width and height 
values, when added to the window origin, must be within bitmap limits. 



OUTPUT PARAMETERS 

pixel-array 

Array of the pixel values (color/intensity) . This is an array of 4-byte 
integers. GPR_$PIXEL_ARRAY_T format is an example of such an array. 

status 

Completion status, in STATUS_$T format. 



NOTES 

* The pixel values from the source window of the current bitmap are stored 
in the pixel array in row-major order, one in each 4-byte integer. 

* To write pixel values from an array to the current bitmap, use 
GPR_$WRITE_PIXELS. 
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GPR_$READ_PIXELS 



LIMITATIONS 

* A program cannot use this routine on a bitmap corresponding to a Display 
Manager frame. 

* A program cannot read pixels values in imaging formats. 
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GPR_$RECrANGLE 



GPR_$RECrANGLE — Fills a rectangle. 

FORMAT 

GPR_$RECTANGLE (rectangle, status) 

INPUT PARAMETERS 

rectangle 

The rectangle in the current bitmap to be filled in. Rectangle is in 
GPR_$WINDOW_T format. This is a two-element array of two-element 
arrays. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* GPR_$RECTANGLE fills in a rectangle with the color/ intensity value 
specified with GPR_$SET_FILL_VALUE. To retrieve the current fill value, 
use GPR_$INQ_FILL_YALUE. 

* See Section 6.2 for more information about filling rectangles. 
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GPIl_$KELEASE_DISPLAY 



GPR_$RELEASE_DISPLM — Decronents a counter associated with the number of 

tiines a display has been acquired. 

GPR_$RELEASE_DISPLM (status) 

INPUT PARAMETERS 
None, 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* GPR_$RELEASE_DISPLAY decrements a counter whose value reflects the 
number of times the display has been acquired. If the counter value 
reaches zero, the routine releases the display, allowing other 
processes, including the Display Manager, to use the display. 

* GPR_$RELEASE_DISPLAY automatically releases the keyboard when it 
releases the display. 

* Programs that call GPR_$EVENTJWAIT may not need to call 
GPR_$RELEASE_DISPLAY, since GPR_$EVENTJWAIT releases the display 
implicitly whenever the process waits for input. 
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GPR_$REa^lAP_CX)IiOR_MEMORY 



GPR_$REMAP_OOIiOI^MEHDRY -— Establishes the single plane of color display 

memory to be accessed directly. 

FORMAT 

GPR_$REMAP_CX)LOR_MEMDRY (plane, status) 

INPUT PARAMETERS 

plane 

Plane for access through storage-pointer, in GPR_$PLANE_T format. This 
is a 2-byte integer. Valid values are 0-7. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NOTES 



When accessing color display memory directly (i.e. by dereferencing the 
pointer returned by GPR_$INQ_BI1MAP_P0INTER) , the program can access 
only one plane at a time. (This is unlike access to multi-plane memory 
bitmaps, in which the first scan line of a plane immediately follows the 
last scan line of the previous plane in virtual memory.) Therefore, a 
program must use GPR_$REMAP_(X)LOR_MENDRY to establish which plane of 
color display memory will be accessible through the pointer returned by 
GPR_$INQ_BI'nyiAP_POINTER. 
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GPR_$REMAP_CX)LOR_MEMORy_l 



GPR_$REiy!AP_CX)LOR_MEMORY_l — Sets the plane of hidden color display memory 

mapped at the address returned by 
GPR_$INQ_BI'IMAP_POINTER. 

FORMAT 

GPR_$REMAP_CX)IiOR_MEMORY_l (plane, status) 

INPUT PARAMETERS 

plane 

Plane for access through storage-pointer, in GPI^$PLANE_T format. This 
is a 2-byte integer. Valid values are 0-7. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* GPR_$REMAP_CX)LOIl_MEMORY_l makes visible the normally hidden frame 1 of 
color display memory. GPR_$REMAP_COLOR_MEM0RY sets frame 0. 
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GPR_$REPLICATE_J(»IT 

GPR_$REPLICATE_FONT -— Creates and loads a modifiable copy of a font. 

FORMAT 

GPR_$REPLICATE_PONT (font-id, repli-font-id, status) 

INPUT PARAMETERS 

font-id 

Identifier of the text font. Iliis is a 2-byte integer. 

OUTPUT PARAMETERS 

repl-font-id 

Identifier of the copied text font. This is a 2-byte integer. 

status 

Completion status, in STATUS_$T format. 



NOTES 

* For a description of fonts and font files, see the DOMAIN System Command 
Reference Manual . 

* To use routines which change fonts, you must first call 
GPR_$REPLICATE_PONT to create a modifiable copy of a font. The 
font-modifying routines include GPR_$SET_CKIARACTER_WIiyffl, 
GPR_$SET_HORIZ(M'AL_SPACING, and GPR_$SET_SPACE_SIZE. These calls 
change only the local copy of the font. If you unload a font and reload 
it, the font is reset to the values in the font file. 
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GPR_$SELECr_CDLOR_FRAME 



GPR_$SELECT_CDLOI^FRAME — Selects whether frame or frame 1 of a plane of 

color display memory is visible. 

FORMAT 

GPR_$SELECr_(X)IiOR_FRAiyiE (frame, status) 

INPUT PARAMETERS 

frame 

A 2-byte integer that denotes which frame is to be visible. Possible 
values are zero or one. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* Normally, frame is visible. 
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GPR_$SET_ACQ_TIME_OUT 



GPR_$SET_AOQ_TIME_CXJT — Establishes the length of time the display will be 

acquired. 

FORMAT 

GPR_$SET_ACQ_TIME_CXIT (timeout, status) 

INPUT PARAMETERS 

timeout 

The maximum real time, in TIME_$CLOCK_T format, for which the program 
can acquire the display. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* If the program has not released the display when the time-out expires 
and another process (for example, the Display Manager) needs the 
display, an acquire time-out fault (SMD_$ACQUIRE_TIMEOUT) is generated 
in the user process. The acquire time-out fault is a warning fault that 
the program can intercept with a cleanup handler or static fault 
handler. If the program does not release the display within a few 
seconds of the acquire timeout fault, a second fault occurs (with the 
status code FAULT_$QUIT) and the program loses control of the display. 

* If this routine is not called, the default time-out value is one 
minute. 
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GPR_$SETJVrTRIBUTE_BLOCK 



GPR_$SET_ArTRIBUTE_BLOCK — Associates an attribute block with the current 

bitmap. 



FORMAT 

GPR_$SET_ATTRIBUTE_BLOCK (attrib-block-desc, status) 

INPUT PARAMETERS 

attr ibHDlock-desc 

The descriptor of the attribute block, in GPR_$ATTRIBUTE_DESC_T format. 
This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To allocate and deallocate attribute blocks, use 
GPR_$ALLOCATE_ATTRIBUaE_BLOCK and GPIL_$DEALLOCATE_ATTRIBUTE_BLOaC. 

* To request the descriptor of the current bitmap's attribute block, use 
GPR_$ATTRIBUTE_BLOCK . 
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GPR_$SET_AUTCLKEFRESH 



GPR_$SET_AUTO_REFRESH — Directs the Display Manager to refresh the window 

automatically. 

fOmhT 

GPR_$SET_AU'ID_REFRESH (auto- refresh, status) 

INPUT PARAMETERS 

auto-refresh 

A Boolean value that indicates whether or not the Display Manager will 
autanatically refresh the application's window. A value of true means 
that auto-refresh is enabled; a value of false (the default) means that 
auto-refresh is disabled. 

OUTPLIT PARAMETERS 

status 

Completion status , in STATUS_$T format. 



NOTES 

* Automatic refresh of windows can affect system performance and reduce 
the amount of disk space available, especially if the application's 
windows are large. 

* As an alternative, the application program can also provide procedures 
that refresh the screen and hidden display; see the routine 
GPR_$SET_REFRESH_ENTRY. 

* Ihis routine implicitly releases and reacquires the display in order to 
communicate with the Display Manager. 

* This routine applies to the current bitmap. When a program changes 
attribute blocks for a bitmap during a graphics session, the auto 
refresh flag is lost unless you set it for the new attribute block. 
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GPI^$SET_BI'nyiAP 



GPR_$SET_BiaMAP — Establishes a bitmap as the current bitmap for subsequent 

operations. 

FORMAT 

GPR_$SET_BI1MAP (bitmap-desc, status) 

INPUT PARAMETERS 

bitmap-desc 

The bitmap descriptor, in GPR_$BITMAP_DESC_T format. This is a 4-byte 
integer that uniquely identifies the bitmap. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* The program can obtain the bitmap descriptor by using GPR_$INQ_BI1MAP. 

* After a bitmap is established, it is called the "current bitmap". 
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GPR_$SET_BIlMAP_DI]yiENSIONS 



GPR_$SET_BIIMAP_DIMENSIONS — Modifies the size and the number of planes of a 

bitmap. 

FORMAT 

GPR_$SET_BITMAP_DIMENSIONS (bitmap-desc, size, hi-plane-id, status) 

INPUT PARAMETERS 

bitmap-desc 

The descriptor of the bitmap, in GPR_$BITO1AP_DESC_T format. This is a 
4-byte integer. 

size 

New width and height of the bitmap, in GPIl_$OFFSET_T format. This is a 
two-element array of 2-byte integers. The first element is the bitmap 
width, in raster units; the second element is the bitmap height, in 
raster units. 

hi-plane-id 

The new identifier of the bitmap's highest plane, in GPI^$PLANE_T 
format. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* A program can use this call to change the size of a bitmap after the 
bitmap has been created. This is useful if the program wishes to 
restrict itself to an upper-left subset of the original bitmap, or to 
use hidden memory on a borrowed display. 

* In direct mode, when you allocate a bitmap, you request a size. You 
may get a smaller size if the Display Manager window is smaller than the 
size you requested. These restrictions apply to resizing bitmaps. Any 
bitmap can be shrunk from its original dimensions in x, y or the highest 
plane. Once the bitmap has been shrunk, it can grow up to its requested 
size. The maximum allowed sizes for x, y and the highest plane for the 
various DOMAIN displays are given in the following table. 
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gpr_$set_bi™ap_dimensions 



max X max Y max high plane 



Monochromatic display 1024 1024 

(either portrait or landscape) 

Color display—Interactive format 

4-bit pixels 1024 2048 3 

8-bit pixels ^ 1024 2048 7 



If a program uses hidden display memory, it must be careful not to 
modify areas that are being used to store fill constants or text fonts. 
The following areas may be used by these functions on the various EX)MAIN 
displays. 

Fill constants: 

Both monochromatic displays: 800 <= X <= 1023 and Y = 1023. 
Color displays: none. 

Stand-alone font: 

Monochromatic portrait display: 800 <= X <= 1023 and <= Y <= 39. 
Monochromatic landscape display: 800 <= X <= 1023 and 983 <= Y <= 1022. 
Color displays: same as monochromatic portrait display, plane only, 

Y offset by 1024. 

User text fonts: (only if text fonts are loaded) 

Monochromatic portrait display: 800 <= X <= 1023 and 40 <= Y <= 1022, 

allocated from top to bottom. 

Monochromatic landscape display: <= X <= 1023 and 800 <= Y <= 1023, 

in columns 224 bits wide, allocated 
top to bottom and left to right. 

Color displays: same as monochromatic portrait display, plane only, 

Y offset by 1024. 

Note that these areas may move, grow or shrink in future DOMAIN software 
releases. Tlierefore, only limited use should be made of hidden display 
memory in conjunction with text or cursor operations. 
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GPR_$SET_CHARACTER_WIDTH 



GPR_$SET_CHARACTEIl_WIDTH — Specifies the width of the specified character in 

the specified font. 

F OR MA T 

GPR_$SET_aiARACrEIi_WIDTH (font- id, character, width, status) 

IN PUT PARAMETERg 

font- id 

Identifier of the text font. This is a 2-byte integer. 

character 

The specified character. This is a CHAR variable. 

width 

Hie width parameter of the specified character. This is a 2-byte 
integer. Possible values are -127 to 127. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 

* To retrieve a character's width, use GPR_$INQ_CHARACTER_WIDra. 

* The initial character widths are defined in the font file. For a 
description of fonts and font files, see the DOMAIN System Command 
Reference Manual . 

* To use routines which change fonts, you must first call 
GPR_$REPLICATE_FC»IT to create a modifiable copy of a font. The 
font-modifying routines include GPIl_$SET_CHARACTER_WIDTH, 
GPR_$SET_HORIZCNTAI^_SPACING, and GPR_$SET_SPACE_SIZE. Hiese calls 
change only the local copy of the font. If you unload a font and reload 
it, the font is reset to the values in the font file. 
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GPR_$SET_CLIPPING_ACTIVE 



GPR_$SET_CLIPPING_ACTIVE — Enables/disables a clipping window for the 

current bitmap. 

FORMAT 

GPR_$SET_CLIPPING_ACTIVE (active, status) 

INPUT PARAMETERS 

active 

A Boolean (logical) value which specifies whether or not to enable the 
clipping window. Set this value to true to enable the clipping window; 
set it to false to disable the clipping window. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* To specify a clipping window, use the routine GPIl_$SET_CLIP_WINDOW. 

* Initially, in bor row-display and frame modes, the clip window is 
disabled. In direct mode, the clip window is enabled and clipped to the 
size of the window. 

* To inquire whether the clip window is enabled, use 
GPR_$INQ_C0NSTRAINT5 . 
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GPR_$SET_CLIP_WINDCW 



GPR_$SET_CLIP_WINDCIW — Changes the clipping window for the current bitmap. 

FORMAT 

GPR_$SET_CLIP_WINDOW (window, status) 

INPUT PARAMETERS 

window 

The new clipping window, in GPR_$WINDOWLT format. This is a two-element 
array of two-element arrays. (In FORTRAN, you can use a two-dimensional 
array. ) 

The first element of GPR_$WINDOW_T specifies the window origin (the top 
left corner coordinate position) in GPR_$POSITION_T format. This is a 
two-element array of 2-byte integers. The first element is the origin's 
x-coordinate; the second element is the y-coordinate. Coordinate values 
must be within the bitmap limits. 

The second element of GPR_$WINDOW_T specifies the window width and 
height, in GPR_$OFFSET_T format. This is a two-elonent array of 2-byte 
integers. The first elonent is the window width, in raster units; the 
second element is the window height, in raster units. Width and height 
values, when added to the corresponding origin coordinate, must be 
within bitmap limits. (See Figure 11-4.) 



CURRENT BITMAP 



CLIPPING WINDOW 
ORIGIN 



CLIPPING WINDOW 




CLIPPING WINDOW WiDTH 



CLIPPING WINDOW HEIGHT 



Figure 11-4. Qipping Window Origin, width. Height 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 
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GPIl_$SET_CLIP_WINDOW 



* The default clip window is the entire bitmap. 

* Pixels outside the clip window in the current bitmap are not modified by- 
subsequent operations. 

* To enable the dip window, use GPR_$SET_CLIPPING_ACTIVE. 

* To request the dimensions of the current clip window, use 
GPR_$INQ_CDNSTRAINTS . 

LIMITATIONS 

* This call is not allowed on the bitmap corresponding to the Display 
Manager frame. 
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GPR_$SET_CDLOR_MAP 



GPR_$SET_CDLOR_MAP — Establishes new values for the cx)lor map. 

FORMAT 

GPR_$SET_CDLOrLMAP (start- index, n-entries, values, status) 

INPUT PARAMETERS 

start- index 

Index of first color value entry, in GPIl_$PIXEL_VALUE_T format. This is 
a 4-byte integer. 

n-entries 

Number of entries. This is a 2-byte integer. Valid values are: 

2, for monochromatic displays 

1-16, for color displays in 4-bit pixel format 

1-256, for color displays in 8-bit or 24-bit pixel format 

values 

Color value entries, in GPR_$COLOR_VECTOR_T format. This is an array of 
4-byte integers. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* For the monochromatic display, the default start- index is 0, n-entries 
is 2, and the values are GPR_$BLACK and GPR_$WHITE. Dark has the value 
GPR_$BLACK, and bright has the value GPIL$WHITE. A program can use this 
routine to redefine the pixel values corresponding to bright and dark 
intensity. 

* For the monochromatic display, if the program provides fewer than two 
values, or if the first two values are the same (both black or both 
white) , the routine returns an error. 

* For the monochromatic display, the graphics primitives simulate a color 
map by modifying the contents of display memory. 

* In direct mode, you must acquire the display before establishing new 
values for the color map. 

* To retrieve the current color map, use GPR_$INQ_GOLOR_MAP. 
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GPR_$SET_CXX)RDINATE_ORIGIN 



GPR_$SET_CXX)RDINA!rE_ORIGIN — Establishes x- and y-offsets to add to all x- 

and y-coordinates used as input to move, line 
drawing, and BLT operations on the current 
bitmap. 



FORMAT 

GPR_$SET_aX)RDINATE_ORIGIN (origin, status) 

INPUT PARAMETERS 

origin 

The new coordinate origin for the bitmap, in GPR_$POSITION_T format. 
This is a two-element array of 2-byte integers. The first element is 
the origin's x-coordinate; the second element is the y-coordinate. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 

* This call affects the x- and y-coordinates input to the following 
routines: GPR^$MOVE, GPR_$LINE, GPR_$POLYLINE, GPR_$MULTILINE, 
GPR_$ADDITIVE_BLT, GPR_$BIT_BLT, and GPIL.$PIXEL_BLT. 

* To retrieve the current coordinate origin, use 
GPR_$INQ_C0ORDINATE_ORIGIN. 

* The default coordinate origin is (0,0). 

LIMITATIONS 

* This routine may not be used on a bitmap corresponding to a Display 
Manager frame. 
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GPR_$SET_ajRSOR_ACTIVE 



GPR_$SET_ajRSOR_ACTIVE — Specifies whether the cursor is displayed. 

FORMAT 

GPR_$SET_ajRSOIL.ACTIVE (active, status) 

INPU T P A I ^ fi fffiTEfiS 

active 

A Boolean (logical) value which specifies whether to display the 
cursor. Set the parameter to true to display the cursor; set it to 
false if you do not want to display the cursor, 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* Initially, the cursor is not displayed. 

* To inquire whether the cursor is currently displayed, use 
GPR_$INQ_CURSOR. 

LIMITATIONS 

* A program may call this routine only while operating in bor row-display 
or direct mode. 
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GPR_$SET_ajRSOR_ORIGIN 



GPR_$SET_aJRSOR_ORIGIN — Defines one of the cursor's pixels as the cursor 

origin. 

FORMAT 

GPR_$SET_ajRSOR_ORIGIN (origin, status) 

INPUT PARAMETERS 

origin 

The position of one cursor pixel (the origin) relative to the entire 
cursor, in GPR_$POSITION_T format. This is a two-element array of 2-byte 
integers. The first element is the pixel's cursor- relative 
x-coordinate. The second element is the pixel's cursor- relative 
y-coordinate. Coordinate values are in the range 0-15, but limited by 
cursor size; the cursor origin cannot be outside the cursor. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format, 

NOTES 

* A program uses GPR_$SET_CURSOR_ORIGIN to designate one cursor pixel as 
the cursor origin. Thereafter, when the cursor is moved, the pixel 
designated as the cursor origin moves to the screen coordinate 
designated as the cursor position. 

* The default cursor origin depends on the default cursor size, which 
depends on the size of the Display Manager's standard font. 

* To inquire about the current cursor origin, pattern, position and 
whether the cursor is enabled, use GPR_$INa_CURSOR. 
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GPR_$SET_ajRS0R_PA1TERN 

GPI^$SET_ajRSOR_PATTERN — Loads a cursor pattern. 

FORMAT 

GPR_$SET_ajRS0R_PA1TERN (cursor-pattern, status) 

INPUT PARAMETERS 

cursor-pattern 

The descriptor of the bitmap which contains the cursor pattern, in 
GPR_$BITMAP_DESC_T format. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* Initially, the cursor pattern is a rectangle, which varies in size 
according to the size of the Display Manager's standard font. A program 
can use GPR_$SET_CURSOR_PATTERN to redefine the cursor pattern. The 
bitmap that represents the cursor pattern consists of one plane, which 
is a maximum of 16x16 pixels in size. 

* To inquire about the current cursor pattern, use GPR_$INQ_CURSOR. 
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GPR_$SET_ajRSOR_POSITION 



GPR_$SET_aJRSOR_POSITION -— Establishes a position on the screen for display 

of the cursor. 



FORMAT 

GPR_$SET_aJRSOR_POSITION (position, status) 

INPUT PARAMETERS 

position 

Screen coordinate position for display of the cursor, in GPR_$POSITION_T 
format. This is a two-element array of two-byte integers. The first 
element is the cursor position's x-coordinate; the second element is the 
y-coordinate. Coordinate values must be within the limits of the 
display in use, as follows: 

X y 



Borrowed Display: 

Monochromatic Portrait: 0-799 0-1023 

Monochromatic Landscape: 0-1023 0-799 

Color: 0-1023 0-1023 

Display Manager Frame: 0-32767 0-32767 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 
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GPR_$SET_ajRSOR_POSITION 



NOTES 



* Cursor position: If a program calls this routine when in bor row-display 
mode, the x- and y-coordinates represent an absolute position on the 
screen. If a program calls this routine when the cursor is inside a 
frame of a Display Manager pad, the x- and y-coordinates are offsets 
from the top left corner of the frame. 

* If the coordinate position would cause any part of the cursor to be 
outside the screen or frame, the cursor moves only as far as the edge of 
the screen. The cursor is neither clipped nor made to disappear. 

* To request the current cursor position, use GPIL$INQ_CURSOR. 

LIMITATIONS 

* In a Display Manager frame, this routine moves the cursor only if the 
cursor is in the window viewing this frame when the call is issued. If 
not, a "next window" command which moves to that window will move the 
cursor to its new position. 
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GPrL$SET_DRAW_VALUE 



GHL$SET_DKM_VALUE — Specifies the cx)lor/ intensity value to use to draw 

lines. 



FORMAT 

GHL$SET.DRM_ VALUE (index, status) 

INPUT PARAMETERS 

index 

The color map index that indicates the current color/ intensity value 
used for drawing lines, in GHL$PIXEL_VALUE_T format. This is a 4-byte 
integer. Valid values are: 

0-1 for monochromatic displays 
0-15 for color displays in 4-bit pixel format 
0-255 for color displ^s in 8-bit or 24-bit pixel format 
-2 for all displays. This specifies using the color/ intensity 
value of the bitmap background as the line drawing value. 
For borrowed displ^s and memory bitmaps, the fill 
background is alw^s zero. For Display Manager frames, this 
is the pixel value in use for the window background. 

status 

Completion status, in STA3US_$T format. 



* To retrieve the current draw value, use GHL$INCL DRAWL VALUE. 

* The default draw value is 1. 

* For monochromatic displays, only the low-order bit of the draw value is 
considered, because monochromatic displays have only one plane. 

* For color displays in 4-bit pixel format, only the four lowest-order 
bits of the draw value are considered, because these displ^s have four 
planes. 

* The color specification parameter is a color map index, not a color 
value. See Section 4.3. 
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GPR_$SET_FILL_BACKGIOJND_VALUE 



GPR_$SET_FIU^BACKGRO[JND_VALUE — Specifies the color/ intensity value used 

for drawing the background of tile fills. 

FORMAT 

GPR_$SET_FILL_BACKGR0U1C)_VALUE (index, status) 

INPUT PARAMETERS 

index 

The color map index that indicates the current color/intensity value 
used for tile fills, in GPR_$PIXEL_VALUE_T format. This is a 4-byte 
integer. Valid values are: 

0-1 for monochromatic displays 
0-15 for color displays in 4-bit pixel format 
0-255 for color displays in 8-bit or 24-bit pixel format 
-1 for all displays. This specifies that the fill background is 
transparent; that is, the old values of the pixels are not 
changed. 
-2 for all displays. This specifies using the color/ intensity 
value of the bitmap background as the fill background. 
For borrowed displays and memory bitmaps, the fill 
background is always zero. For Display Manager frames, this 
is the pixel value in use for the window background. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



* To retrieve the current background value, use 
GPIL.$INQ_FILL_BACKGKXJND_VALUE. 

* The default fill background value is -2. 

* This routine defines the background fill value for 1-bit patterns. In 
all other fill patterns, the values set with this routine are ignored. 
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GPR_$SET_FILL_PATTERN 



GPR_$SET_FILL_PA1TERN — Specifies the fill pattern used for the current 

bitmap. 

FORMAT 

GPR_$SET_FILL_PATTERN (pattern, scal6, status) 

INPUT PARAMETERS 

pattern 

The descriptor of the bitmap containing the fill pattern, in 
GPR_$BI'IMAP_DESC_T format. This is a 4-byte integer. See restriction 
below. 

scale 

The number of times each bit in this pattern is to be replicated before 
proceeding to the next bit in the pattern. This is a 2-byte integer. 
See restriction below. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NOTES 

* Currently, the tile pattern must be stored in a bitmap that is 32x32 
pixels by n planes. The scale factor must be one. Any other pattern 
size or scale value results in an error. 

* To retrieve the current fill pattern for the current bitmap, use 
GPR_$INQ_FILL_PATrERN. 

* With a one-plane bitmap as the pattern, the pixel values used are those 
set by GPR_$SET_FILL_VALUE and GPIL.$SET_FILL_BACKGROUND_VALUE. Pixels 
corresponding to "1" bits of the pattern are drawn in the fill value: 
pixels corresponding to "0" bits of the pattern are drawn in the fill 
background value. 

* With a multiplane bitmap as the pattern, the pixel values used are those 
contained in the pattern bitmap. 

* To re-establish solid fills, set the fill pattern descriptor to 
GPR_$NIL_BI'IMAP_DESC. 
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GPR_$SET_FILL_VALUE 



GPR_$SET_FIIjL_VMiUE — Specifies the color/intensity value to use to fill 

circles, rectangles, triangles, and trapezoids. 



FORMAT 

GPR_$SET_FILL_ VALUE (index, status) 

index 

The color map index that indicates the current fill color/ intensity 
value, in GHL$PIXEL_VRLljaELT format. This is a 4-byte integer. Valid 
values are: 

0-1 for monochranatic displ^s 

0-15 for color displays in 4-bit pixel format 

0-255 for color displays in 8-bit or 24-bit pixel format 

status 

CcmpLetion status, in STAIUS_$T format. 



* To retrieve the current fill value, use GrR_$INQ_ FILL-VALUE. 

* The default fill value is 1. 

* For monochromatic displays, only the low-order bit of the fill value is 
considered, because monochromatic displ^s have only one plane. 

* For color displ^s in 4-bit pixel format, only the four Icwest-order 
bits of the fill value are considered, because these displays have four 
planes. 

* The color specification parameter is a color map index, not a color 
value. See Section 4.3. 
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GPIl_$SET_H0RIZONTMi_SPACING 



GPR_$SET_HORIZONTAri_SPACING — Specifies the parameter for horizontal spacing 

of the specified font. 

FORMAT 

GPR_$SET_HORIzaJTAL_SPACING (font- id, horizontal-spacing, status) 

INPUT PARAMETERS 

font- id 

The identifier of the text font. This is a 2-byte integer. 

horizontal-spacing 

The horizontal spacing parameter of the specified font. This is a 
2-byte integer. Possible values are -127 to 127. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



^PTES 

* Use GPR_$INQ_HORIZCNTAL_SPACING to retrieve a font's horizontal 
spacing. 

* The initial horizontal spacing is defined in the font file. For a 
description of fonts and font files, see the DOMAIN System Command 
Reference Manual , 

* To use routines which change fonts, you must first call 
GPR_$REPLICATE_FONT to create a modifiable copy of -a font. The 
font-modifying routines include GPR_$SET_CElARACTER_WIiyffl, 
GPR_$SET_HORIZ0NTAL_SPACING, and GPI^$SET_SPACE_SIZE. These calls 
change only the local copy of the font. If you unload a font and reload 
it, the font is reset to the values in the font file. 
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GPR_$SET_IMAGING_PORMT 

GPIL$SET_IMAGING_PORMAT — Sets the imaging format of the color display. 

FORMAT 

GPR_$SET_IMAGING_FORMAT (format, status) 

INPUT PARAMETERS 

format 

A format type that specifies pixel and bit values. Use 
GPR_$IMAGING_PORMAT_T format. This is a two-bute integer. Valid 
values and hardware configurations are the following: 

Either two- or three-board: 
GPR_$INTERACTIVE 

IWo-board only: 
GPI^$IMAGING_1024xl024x8 

Three-board only: 
GPR_$IMAGING_512x512x24 



OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NQ TE g 

* To retrieve the current imaging format, use GPIL$INQ_IMAGING_PORMAT. 

* To use GPR_$SET_IMAGING_FORMAT, you must be in borrow display mode and 
be using a color node. 

* See Section 2.3 for more information about imaging formats. 

* Imaging formats support only limited GPR operations — displaying pixel 
data and changing the color map. Other functions will return error messages. 

* 1024x1024x8 imaging format is not suj^rted on a three-board system 
as it offers no advantages over interactive formats. 
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GPR_$SET_INPUT_SID 



GPR_$SET_INPUT_SID — Specifies the input pad from which graphics input is to 

be taken. 



FORMAT 

GPR_$SET_INPUT_SID (stream- id, status) 

INPUT PARAMETERS 

stream-id 

The stream ID that GPR software will use for input in frame mode, in 
STREAM_$ID_T format. The stream must be a Display Manager input pad. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* Programs use this call only when they call input routines in frame mode 
(GPR_$EVENT_WAIT and GPR_$CCMD_EVENT_WAIT) . 

* If this routine is not called, the default stream ID is STEyEAM_$STDIN (a 
stream ID of zero) . 

* To work properly, the input pad must be the pad associated with the 
transcript pad passed to GPR_$INIT. STREAM_$STDIN is associated with 
STREAM_$STDOUT in this way in a normal Shell process window. Other 
process input pads derive their association from the PAD_$CREATE call 
that created them. 
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GPR_$SET_LINE_PAITERN 



GPR_$SETLINE_PATTERN -— Specifies the pattern to use in drawing lines. 

FORMAT 

GPR_$SET_LI^E_PATTERN (repeat, pattern, length, status) 

INPUT PARAMETERS 

repeat 

ihe replication factor for each bit in the pattern. Ohis is a 2-byte 
integer. 

pattern 

The bit pattern, left justified, in GPR_$LINE_PATrERN_T format. Tliis 
is a four-element array of 2-byte integers. 

length 

The length of the pattern in bits. This is a 2-byte integer in the 
range of to 64. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



* GPR_$LINE, GPR_$POLYLINE, GPI^$MULTILINE use the pattern/style most 
recently defined by either GPR_$SET_LINE_PATFERN or GPIl_$SET_LINESTYLE. 
The actual bits in the integers define the line pattern. You should set 
the first bit in the pattern; otherwise, the vectors you draw will not 
show the beginning of the line correctly. 

* Specifying the value of for either repeat or length results in a solid 

1 1 rta 



line. 



* 



You may also set a line pattern with GPR_$SET_LIMESTYLE. The pattern is 
defined by the parameter GPI^$DOTTED. 



* Within each element of the bit pattern, the bits are used in order of 
decreasing significance. This starts with the most significant bit of 
entry 1 down to the least significant of entry 4. 

* Use GPR_$INQ_LINE_PATrERN to retrieve the current line pattern. This 
routine returns the pattern set explicitly with GPR_$SET_LINE_PATTERN or 
set implicitly with GPR_$SET_LINESTYLE. 
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GPR_$SET_LINESTYLE 



GPR_$SET_LINESTYLE — Sets the line-style attribute of the current bitmap. 

FORMAT 

GPR_$SET_LINESTYLE (style, scale, status) 

INPUT PARAMETERS 

Style 

The style of line, in GPR_$LINESTXLE_T format. Possible values are 
GPR_$SOLID and GPR_$DOTTED. This is a 2-byte integer. 

scale 

The scale factor for dashes if the style parameter is GPIl_$DOTTED. ^is 
is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* When the line-style attribute is GPIl_$DOTTED, lines are drawn in 
dashes. The scale factor determines the number of pixels in each dash 
and in each space between the dashes. 

* For greater flexibility in setting line styles, use 
GPR_$SET_LINE_PATTERN. 

* Use GPR_$INQ_LINESTYLE to retrieve the current line-style attribute. 
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GPR_$SET_OBSajRED_OPT 



GPR_$SET_CBSajRED_OPT — Establishes the action to be taken when a window to 

be acquired is obscured. 

GPR_$SET_OBSajRED_OPT (if-obscured, status) 

INPUT PARAMETERS 

if -obscured 

If the window to be acquired by GPIL.$ACQUIRE_DISPLAY is obscured, this 
argument specifies, in GPR_$OBSa]RED_OPTION_T format, the action to be 
taken. This is a 2-byte integer. The possible actions are: 

GPR_$POP_IF_OBS Pop the window. 

GPIl_$ERR_IF_CBS Return an error and do not 

acquire the display. 

GPR_$BLOCK_IF_OBS Block display acquisition 

until the window is popped. 

GPR_$OI^IF_OBS Acquire the display even though the window 

is obscured. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* If this routine is not called, the action to be taken defaults to 
GPR_$ERR_IF_OBS. 

* These options apply whenever the display is acquired, either by 
GPR_$ACQUIRE_DISPLAy or implicitly by GPIi_$EVENT_WAIT. 

* If the program specifies the option GPR_$ERR_IF_OBS, it must check the 
status code returned from GPR_$ACQUIRE_DISPLAX" or GPIl_$EVENT_WAIT before 
calling any drawing routines. 

* When a program specifies OK_$IF_OBS, the output is performed even when 
the window is obscured. This output may overwrite other Display Manager 
windows. 

* Use GPR_$INQ_VIS_LIST to retrieve a list of visible sections of an 
obscured window. 
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GPIl_$SET_PLANE_MASK 



GPR_$SET_PLANE_MASK — Establishes a plane iiask for subsequent write 

operations. 

FORMAT 

GPR_$SET_PLANE_MASK (mask, status) 

INPUT PARAMETERS 

mask 

The plane mask, which specifies which planes to use, in GPR_$MASK_T 
format. FORTE^AN programmers should encode the plane mask in a 2-byte 
integer in the range 0-255. Pascal programmers can use a variable with 
a SET OF 0..7 to set the bits directly. If, for example, the third bit 
is ON, the third plane will be used in subsequent operations. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* The default mask specifies that all planes are used. 

* Operations occur only on the planes specified in the mask. A program 
can use this routine, for example, to perform raster operations on 
separate planes or groups of planes in the bitmap. 

* Using the mask, a program can partition the 8-bit pixels into subunits. 
For example, the program can use planes 0-3 for one picture and planes 
4-7 for another. Thus, one bitmap may contain two color pictures. This 
does not, however, increase the number of colors available for one 
bitmap. 

* To retrieve the current plane mask, use GPR_$INQ_OONSTRAINTS. 
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GPR_$SET_RASTEIl_OP 



GPR_$SET_RASTEIi_OP — Specifies a new raster operation for iDoth BLTS and 
lines. 



FORMAT 

GPR_$SET_RASTER_OP (plane- id, raster-op, status) 

INPUT PARAMETERS 

plane- id 

Identifier of the bitmap plane involved in the raster operation, in 
GPR_$PLANE_T format. This is a 2-byte integer. Valid values are zero 
through the identifier of the bitmap's highest plane. 

raster-op 

Raster operation code, in GPR_$RASTER_OP_T format. This is a 2-byte 
integer. Possible values are zero through fifteen. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

WTES 

* See Table 3-1 for a listing of the raster operation codes and their 
functions. 

* Use GPR_$INQ_RASTER_OPS to retrieve the current BLT raster operation. 

* The initial raster operation is 3. This operation assigns all source 
bit values to new destination bit values. 

* The following is a list of the op codes and logical functions of the 
sixteen raster operations and a truth table of the raster operations. 
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GPIl_$SET_RASTER_OP 



Raster Operations and Their Functions 



Op Code 



Logical Function 




1 
2 
3 
4 
5 
6 
7 
8 

9 
10 
11 
12 
13 
14 

15 



Assign zero to all new destination values. 

Assign source AND destination to new destination. 

Assign source AND complement of destination to new destination. 

Assign all source values to new destination. 

Assign complement of source AND destination to new destination. 

Assign all destination values to new destination. 

Assign source EXCLUSIVE OR destination to new destination. 

Assign source OR destination to new destination. 

Assign complement of source AND complement of destination to 

new destination. 
Assign source EQUIVALENCE destination to new destination. 
Assign conplement of destination to new destination. 
Assign source OR complenent of destination to new destination. 
Assign complement of source to new destination. 
Assign complement of source OR destination to new destination. 
Assign complenent of source OR complement of destination to 

new destination. 
Assign 1 to all new destination values. 



Raster Operations: Truth Table 



SOURCE 

BIT 

VALUE 


DESTINATION 

BIT 

VALUE 


RESUL'TANT BIT VALUES FOR 
01234567 


IHE POT .T .OWING OP CODES: 
8 9 10 11 12 13 14 15 




1 

1 



1 

1 


00000000 
00001111 
00110011 
01010101 


11111111 
00001111 
00110011 
01010101 
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GPR_$SET_REFRESH_ENTRY 



GPR_$SET_REFRESH_ENTRy — Specifies the entry points of application-supplied 

procedures that refresh the displayed image in a 
direct window and hidden display memory. 

FORMAT 

GPR_$SET_REFRESH_ENIRY (window^procedure, disp-mem-procedure, status) 

INPUT PARAMETERS 

window-procedure 

Entry point for the application-supplied procedure that refreshes the 
Display Manager window, in GPIl_$RWirLPR_T format. This is a pointer to 
a procedure. 

di sp-mem-procedur e 

Entry point for the application-supplied procedure that refreshes the 
application's hidden display memory, in GPIl_$RHDM_PR_T format, which is 
a pointer to a procedure. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

I^QTES 

* The Display Manager determines when the window needs to be redrawn based 
on the amount of activity the user generates on the screen. When a 
redrawing operation is necessary, the Display Manager calls the 
application-supplied procedure the next time that the application 
acquires the display. IWo input parameters are passed to the window 
refresh procedure: 

• unobscured — When false, this Boolean value indicates that the 
window is obscured. 

• position_changed — When true, this Boolean value indicates that 
the window has moved or grown since the display was released. 

The "pointer to procedure" data t^pe is an extension to the Pascal 
language. See the Pascal User's Guide for an explanation of this 
extension. 

* This routine requires you to pass procedure pointers. To do so in 
FORTRAN programs, use the following technique. First declare the 
subroutines to be passed as EXTERNAL. Then pass their names using the 
lADDR function to simulate the Pascal pointer mechanism. For example: 
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GPil_$SET_REFRESH_ENTRY 



EXTERNAL REFRESHJWINDOW, REFRESH_HDM 



CALL GPR_$SET_REFRESH_ENTRY (IADDR(REFRESH_WINDOW) ,IADDR(REFRESH_HDM) , 

STATUS) 

* In FORTRAN, use (not NIL) to indicate a zero value. 

* The cxDntents of hidden display monory nay be altered by an intervening 
process. If this occurs, the application-supplied procedure for 
display monory refresh is called to reconstruct hidden display memory 
when the application reacquires the display (with GPI^$ACQUIRE_DISELAy 
or GPR_$EVENT_WAIT) . 

* You may use GPR_$SET_REFRESH_ENTRY to specify entry points for window 
refresh and hidden display memory refresh procedures. When you do so, 
the display memory refresh procedure is called before the window refresh 
procedure. These procedures are never called asynchronously. Ihey are 
called only when the display is acquired. Programs that only need to 
define one entry point should specify a null pointer to the appropriate 
parameter. 

* Successive calls to GPR_$SET_REFRESH_ENTRY override previously defined 
entry points. 

* This routine applies to the current bitmap. When you have multiple 
displayed bitmaps, you may establish a call to GPIl_$SET_REFRESH_ENTRY 
for each bitmap. When a program changes attribute blocks for a bitmap 
during a graphics session, the refresh entry procedures are lost unless 
you set them for the new attribute block. 

* Applications can also direct the Display Manager to refresh the window 
automatically; see the routine GPR_$SET_AUTO_REFRESH. 
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GPR_$SET_SPACE_SIZE 



GPR_$SET_SPACE_SIZE — Specifies the size of horizontal spacing for the 

specified font. 

FORMAT 

GPR_$SET_SPACE_SIZE (font-id, space-size, status) 

INPUT PARAMETERS 

font-id 

Identifier of the text font. Ihis is a 2-byte integer. 

space-size 

The space size of the specified font. This is a 2-byte integer. 
Possible values are -127 to 127. 

OUTPUT PARAMETERS 

status 

Completion status, in STATOS_$T format. 



NOTES 

* To retrieve a font's space size, use GPIi_$INQ_SPACE_SIZE. 

* The initial character widths are defined in the font file. For a 
description of fonts and font files, see the DOMAIN System Command 
Reference Manual . 

* To use routines which change fonts, you must first call 
GPR_$REPLICATE_FONT to create a modifiable copy of a font. The 
font-modifying routines include GPR_$SET_CEiARACTER_WIDTH, 
GPIi_$SET_HORIzaWAL_SPACING, and GPR_$SET_SPACE_SIZE. Ohese calls 
change only the local copy of the font. If you unload a font and reload 
it, the font is reset to the values in the font file. 

* The space size is the number of pixels to skip in the horizontal 
direction when you include a character that is not in the font. 
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GPR_$SET_TEXT_BACKGRDUND_VALUE 



GHU$SET_TEXT_BACKGFCUND_VALUE — Specifies the cx>l or/ intensity value to use 

for text background. 

FORMAT 

GHl_$SET_TEDCT3AaCGRaJND_VALUE (index, status) 

I t ff>UT PJ^tRfilVlETERS 

index 

The xjolor map index that indicates the current color/ intensity value 
used for the text background, in GER_$PIXEI4_VMjUE_T format. Ihis is a 
4-byte integer. Valid values are: 

0-1 for monochropatic displ^s 
0-15 for color displays in 4-bit pixel format 
0-255 for color displays in 8-bit or 24-bit pixel format 
-1 for all displays. This specifies that the text background is 
transparent; that is, the old values of the pixels are not 
changed. 
-2 for all displays. This specifies using the col or/ intensity 
value of the bitmap background as the text background. 
For borrowed displays and memory bitmaps, this value 
is always zero. For Display Manager frames, this is 
the pixel value in use for the window background. 

OqTPPT P J\ RAMETER S 

status 

Completion status, in STAIUS_$T format. 

NOTES 

* To retrieve the current text background value, use GHU$INQ_VALUES, 

* The default text background value is -2. 

* For monochromatic displ^s, only the lew-order bit of the text 
background value is considered, because monochromatic displ^s have only 
one plane, 

* For color displ^s in 4-bit pixel mode, only the four Icwest-order bits 
of the text background value are considered, because these displ^s have 
four planes. 

* The color specification parameter is a color map index, not a color 
value. See Section 4.3. 
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GPR_$SET_'IEXT_PONT 

GER_$SET_TEXT_PONT — Establishes a new font for subsequent text operations. 

Kmh T 

GH^$SET_TEXr_K)NT (font-id, status) 

font-id 

Identifier of the new text font. This is a 2-b7te integer. 

OUTPUT PARAMETERS 

status 

CoppLetion status, in STAIUS_$T format. 

* Obtain the font- id when loading a font with GH^$LOAD_PONT_FILE. 

* To request the identifier of the current font, use GH^$INQ_TEXT. 

* There is no default text font. A program must load and set the font. 

* Call GPEl_$SET_TEXT_PONT for each main memory bitmap. Otherwise, an 
error is returned (invalid font id) . 
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GPIl_$SET_1EXT_PATH 

GPIi_$SET_TEXT_PATH — Specifies the direction for writing a line of text. 

FORMAT 

GPR_$SET_'IEXT_PATO (direction, status) 

INPUT PARAMETERS 

direction 

The direction used for writing text, in GPIl_$DIRECTION_T format. 
Possible values are GPR_$UP, GPR_$DCIWN, GPR_$LEFT and GPR_$RIGHT. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

I ^Q TE g 

* To retrieve the current text path, use GPIL$INQ_1EXT_PATH. 

* The initial text path is GPR_$RIGHT. 
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GPR_$SET_TEXTJVALUE 

GP!El_$SEaLTEXr_VMjUE — Specifies the color/ intensity value to use for writing 

text. 

FORMAT 

GHL.$SETLTE2CT_VRLUE (index, status) 

I NPUT P ^ ^R fiMgTEI^ 

index 

The color map index that indicates the current col or/ intensity value 
used for writing text, in GH^$PIXEL_VALUE_T format. This is a 4-byte 
integer. Valid values are: 

0-1 for monochromatic displays 

0-15 for color displays in 4-bit pixel format 

0-255 for color displays in 8-bit or 24-bit pixel format 

OUTPUT ?pmmm^ 

status 

Campletion status, in STA!IUS_$T format. 

N O TE S 

* To retrieve the current text value, use GHL-$INQ_VAL11ES. 

* The default text value is 1 for borrowed displays, memory bitmaps, and 
Display Manager frames on monochromatic displ^s; for Display Manager 
frames on color displays. 

* For monochromatic displays, only the lew-order bit of the text value is 
considered, because monochromatic displays have only one plane. 

* For color displays in 4-bit pixel format, only the four Icwest-order 
bits of the text value are considered, because these displays have four 
planes. 

* The color specification parameter is a color map index, not a color 
value. See Section 4.3. 
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GPI^$SET_WINDOWLID 



GPR_$SET_WINDOWLID ~ Establishes the character that identifies the current 

bitmap's window. 

FORMAT 

GPR_$SET_WINDOWLID (character, status) 

INPUT PARAMETERS 

character 

Hie character that identifies the current bitmaps 's window. This is 
data type CHAR. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 

NOTES 

* This character is returned by GPR_$EVENT_WAIT and GPR_$COND_EVENT_WAIT 
when they return GPR_$ENTERED_WINDOW events. The character indicates 
which window was entered. 

* The character 'A' is the default value of the window identification for 
all windows. 

* You may assign the same character to more than one window. However, if 
you do so, you cannot distinguish input from the two windows. 
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GPR_$SPLI^E_CUBIC_P 



GPR_$SPLINE_aBIC_P — Draws a parametric cubic spline through the control 

points. 

FORMAT 

GPR_$SPLINE_CUBIC_P (x, y, npositions, status) 

INPUT PARAMETERS 

X 

List of the x-coordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$CC)ORDINATE_ARRAY_T 
format is an example of such an array. Ohe values must be within the 
bitmap limits unless clipping is enabled. 

y 

List of the y~coordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$CXX)RDINATE_ARRAY_T 
format is an example of such an array. The values must be within the 
bitmap limits unless clipping is enabled. 

npositions 

Number of coordinate positions. This is a 2-byte integer in the range 
1-32767. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 



NOTES 



GPR_$SPLINE_CUBIC_P draws a smooth curve starting f ran the current 
position, through each of the specified points. 

After the spline is drawn, the last point becomes the current position. 

The specified coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
positions are the points through which the spline is drawn. 

An error is returned if any two consecutive points are equal. 

When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPil_$SPLINE_CUBIC_X 



GPR_$SPLINE_CUBIC_X — Draws a cubic spline as a function of x through the 

control points. 

FORMAT 

GPR_$SPLIlSE_aiBIC_X (x, y, npositions, status) 

INPUT PARAMETERS 
X 

List of the x-coordinates of all the successive positions. Tliis is a 
one-dimensional array of 2-byte integers. GPR_$CCX)RDINATE_ARRAY_T 
format is an example of such an array. The values must be within the 
bitmap limits unless clipping is enabled. 

y 

List of the y-coordinates of all the successive positions. lliis is a 
one-dimensional array of 2-byte integers, GPR_$COORDINATE_ARRAy_T 
format is an example of such an array. The values must be within the 
bitmap limits unless clipping is enabled. 

npositions 

Number of coordinate positions. This is a 2-byte integer in the range 
1-32767. 

OUTPPT PARAMETERS 

status 

Completion status, in STATaS_$T format. 



NOTES 

* GPR_$SPLINE_aBIC_X draws a smooth curve starting from the current 
position and through each of the specified points. 

* After the spline is drawn, the last point becomes the current position. 

* The specified coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
positions are the points through which the spline is drawn. 

* An error is returned if any x-coordinate is less than or equal to a 
previous x-coordinate. Ihe x-coordinate array must be sorted into 
increasing order. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPR_$SEI:,I^E_aJBIC_Y 



GPR_$SPLIME_CUBIC_y — Draws a cubic spline as a function of y through the 

control points. 

FORMAT 

GPR_$SPLIKE_CUBIC_Y (x, y, npositions^ status) 

INPUT PARAMETERS 

X 

List of the x-coordinates of all the successive positions. This is a 
one-diinensional array of 2-byte integers. GPIi_$CXX)RDINATE_AE^RAY_T 
format is an example of such an array. The values must be within the 
bitmap limits unless clipping is enabled. 

y 

List of the y-coordinates of all the successive positions. This is a 
one-dimensional array of 2-byte integers. GPR_$CXX)RDINATE_ARRAY_T 
format is an example of such an array. The values must be within the 
bitmap limits unless clipping is enabled. 

npositions 

Number of coordinate positions. This is a 2-byte integer in the range 
1-32767. 



OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NOTES 

* GPR_$SPLINE_CUBIC_Y draws a smooth curve starting from the current 
position and through each of the specified points. 

* After the spline is drawn, the last point becomes the current position. 

* The specified coordinates are added to the corresponding elements of the 
coordinate origin for the current bitmap. The resultant coordinate 
positions are the points through which the spline is drawn. 

* An error is returned if any y-coordinate is less than or equal to a 
previous y-coordinate. The y-coordinate array must be sorted into 
increasing order. 

* When you have clipping enabled, you can specify coordinates outside the 
bitmap limits. With clipping disabled, specifying coordinates outside 
the bitmap limits results in an error. 
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GPIl_$START_PGa^ 



GPR_$START_PGCN — Defines the starting position of a polygon boundary loop 

of edges. 

FORMAT 

GPR_$START_PGON (x, y, status) 

INPUT PARAMETERS 
X 

The x-coordinate, in GPR_$CXX}RDINATE_T format. This is a 2-byte 
integer. Its values must be within bitmap limits, unless clipping is 
enabled. 



y 



The y-coordinate, in GPR_$COORDINATE_T format. This is a 2-byte 
integer. Its values must be within bitmap limits, unless clipping is 
enabled. 



OUTPUT PARAMETERS 



status 

Completion status, in STATUS_$T format. 

NDTES 



* GPR_$START_PGC»I defines the first point in a polygon boundary loop of 
edges. This routine is used in conjunction with GPR_$PGON_POLYLINE to 
define a connected series of edges composing one closed loop of a 
polygon's boundary. To see the polygon, you must fill it using either 
GPR_$CLOSE_FILL_PG(^ or GPR_$CLOSE_RETORN_PGC»I and GPR_$MULTITRAPEZOID. 

* This routine closes any previously open loop of edges by connecting its 
last endpoint to its first endpoint with an edge. Then, the routine 
starts the new loop. 

* See Section 6.2 for more information about polygons. 
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GPR_$TERMINATE 



GPR_$TERMINME — Tenninates the graphics primitives package. 

FORMAT 

GPR_$TERMINATE (delete-display, status) 

INPUT PARAMETERS 

delete-display 

A Boolean (logical) value which specifies whether to delete the frame of 
the Display Manager pad. If the program has operated in a Display 
Manager frame and needs to delete the frame at the end of a graphics 
session, set this value to true. If the program needs to close, but not 
delete the frame, set this value to false. If the program has not used 
a Display Manager frame, the value is ignored. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NOTES 



GPR_$TERMINATE deletes the frame regardless of the value of the 
delete-display argument in the following case. A BLT operation from a 
memory bitmap has been done to a Display Manager frame since the last 
time GPR_$CLEAR was called for the frame. 
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GPR_$TEXT 



GPR_$TEXT — Writes text to the current bitmap, beginning at the current 
position. 



FORMAT 

GPR_$TEXT (string, string-length, status) 

INPUT PARAMETERS 

String 

The string to write, in GPR_$STRING_T format. Tliis is an array of 
characters. 

string-length 

Number of characters in the string. This is a 2-byte integer. The 
maximum value is 256. 

OUTPUT PARAMETERS 

Status 

Completion status, in STATUS_$T format. 



NOTES 

* GPR_$TEXT always clips to the edge of the bitmap, regardless of whether 
clipping is enabled. 

* GPR_$TEXT writes the characters in the current font which correspond to 
the ASCCI values of the characters in the specified string. If the font 
does not have a character which corresponds to a character in the 
string, GPR_$TEXT leaves a space. 

* Text is written at the current position. The origin of the first 
character of the character string is placed at the current position. 
Generally, the origin of the character is at the bottom left, exluding 
descenders of the character. 

* Upon completion of the GPR_$TEXT routine, the current position is 
updated to the coordinate position where a next character would be 
written. This is the case even if the string is partly or completely 
clipped. However, the current position always remains within the 
boundaries of the bitmap. 
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GPR_$TRAPEZOID 



GPR_$TE^APEZOID — Draws and fills a trapezoid. 

FORMAT 

GPR_$TRAPEZOID (trapezoid, status) 

INP UT PAI^Af^ETERS 

trapezoid 

The trapezoid in the current bitmap to be filled in. Trapezoid is in 
GPR_$TRAP_T format, which is a two-element array in GPIi_$HORIZ_SEG_T 
format. The first array element is the top horizontal segment of the 
trapezoid; the second array element is the bottom horizontal segment. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

* GPR_$TRAPEZOID fills in a trapezoid with the color/intensity value 
specified with GPR_$SET_FIIl4_VALUE. To retrieve the current fill value, 
use GPR_$INQ_FILL_YALUE. 

* The GPR routiiies define a trapezoid as a quadrilateral with two 
horizontally parallel sides. 

* See Section 6.2 for more information about filling trapezoids. 
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GPIl_$TRIANGLE 



GPR_$TRIANGLE — Fills a triangle. 

FORMAT 

GPR_$TRIANGLE (vertex-1, vertex-2, vertex-S, status) 

INPUT PARAMETERS 

vertex-1 

The first vertex of the triangle, in GPR_$P0SITI0N_T format. This is a 
two-element array of 2-byte integers describing an x- y-coordinate 
position in the bitmap. 

vertex-2 

The secx)nd vertex of the triangle, in GPII_$P0SITI0N_T format. This is 
a two-elonent array of 2-byte integers describing an x- y-coordinate 
position in the bitanap. 

vertex-3 

The third vertex of the triangle, in GPR_$POSITION_T format. This is a 
two-element array of 2-byte integers describing an x- y-coordinate 
position in the bitmap. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NQ TE g 

* GPR_$TRIANGLE fills in a triangle with the col or/ intensity value 
specified with GPR_$SET_FILL_VALUE. 

* To retrieve the current fill value, use GPR_$INQ_FIIiL_VALUE. 

* See Section 6.2 for more information about filling triangles. 
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GPR_$UNLOAD_Jt»JT_FILE 



GPR_$UNLQAD_PONT_FILE — Unloads a font that has been loaded by 

GPR_$LQADJX)NT_FILE. 



FORMAT 

GPR_$UNL0ADJONT_FILE (font-id, status) 

INPUT PARAMETERS 

font-id 

Font identifier. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

t^QTEg 

* The font- id is returned when a program loads a file with the routine 
GPR_$LOAD_PONT_FILE. 



User Callable Routines 11-146 



GPIl_$WAIT_FRAME 



GPR_$/7AIT_FRAME — Waits for the current frame refresh cycle to end before 

executing operations that modify the color display. 

FORMAT 

GPR_$WAIT_FRAME (status) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 

NOTES 

* This routine is for use on color displays only. 

* Operations that modify the color display include block transfers, 
drawing lines, and writing text. 

* This routine is useful primarily for animation. It delays execution of 
display modifications until the scan beam has completely covered the 
screen. 

* A program can also use this routine to synchronize changes to the color 
map with the beginning of the frame. 
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GPR_$WRITE_PIXELS 



GPR_$WRITE_PIXELS — Writes the pixel values from a pixel array into a window 

of the current bitmap. 

FORMAT 

GPR_^VRITE_PIXELS (pixel-array, destination-window, status) 

INPUT PAI^AMETERS 

pixel-array 

Array from which to write pixel values (color/ intensity) . This is an 
array of 4-byte integers. GPR_$PIXEL_ARRAY_T format is an example of 
such an array, 

destination-window 

Rectangular section of the current bitmap into which to write the pixel 
values, in GPR_$WINDOW_T format. This is a two-element array of 
two-element arrays. (In FORTRAN, you can use a two-dimensional array.) 

The first element of GPR_$WIN[XM_T specifies the window start origin 
(top left corner) , in GPI^$POSITION_T format. This is a two-elanent 
array of 2-byte integers. The first element is the origin's 
x-coordinate; the second element is the y-coordinate. Coordinate values 
must be within the bitmap limits. 

The second element of GPR_$WINDCW_T specifies the window width and 
height, in GPR_$OFFSET_T format. This is a two-elonent array of 2-byte 
integers. The first element is the window width, in raster units; the 
second element is the window height, in raster units, width and height 
values, when added to the window origin, must be within the bitmap 
limits. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS_$T format. 
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GPR_$WRITE_PIXELS 



NOTES 



* The pixel values in the pixel array, one in each 4~byte integer, are 
stored in the destination window of the bitmap in row^irajor order. 

* For monochromatic displays, only the low-order bit of each pixel value 
is significant. 

* For color displays in 4-bit pixel format, only the four lowest-order 
bits of each pixel value are considered because the bitmaps have four 
planes, 

* GPR_$WK[TE_PIXELS overwrites the old contents of the bitmap. 

* To read pixel values from the current bitmap into an array, use 
GPR_$READ_PIXELS. 



LIMITATIONS 

* A program cannot use this routine on a bitmap corresponding to a Display 
Manager frame. 
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CHAETER 12 



GRAEHICS MAP FILES 



A grajAiics irap file, or GMF, is an image of the grajAiic infonration in a 
bitirap. Each bit in the GMF represents the state of one visible point on the 
display. On DOMAIN cx)lor nodes, where irore than one plane is used to 
represent visible information, a GMF stores the state of only one plane, 
typically plane 0. 

Once you have stored image data in a GMF, you can restore it to the display 
or produce a printed copy of the image. The GMF contains information that 
helps the GMF manager or amplication prograir interpret the contents of the 
GMF. For instance, the GMF mey indicate the following: the physical density 
of the original image, whether "1" bits in the file correspond to light or 
dark points on the display, and the dimensions of the display area stored in 
the GMF. A GMF can contain the contents of an entire plane or ary specified 
rectangular portion of the plane (sutplane). 

In Software Releases 6.0 and earlier, GMFs were called gr allies metafiles. 

Ihe calls to the GMF manager begin with the letters GMF. To store image 
data in a GMF, you typically use GMF_$OPEN to create or open the GMF, then 
use GMF_$OOPy_ELME to specify the information to be copied into the GMF, 
then close the GMF with GMF_$CLOSE. 

The GMF_$(DPX_HiANE copies a plane of displ^ merory. To make a GMF of ai^ 
rectangular area on the display, regardless of its position, use the more 
general call GMF_$aOPY_SUBPLANE. 

Ihe GMF_$RESTORe_HiANE call returns to the screen any image data that is 
stored in a specified GMF. To use this call, the node must be in 
borrcw-displ^ mode. The call changes a rectangular portion of the displ^, 
with the size determined ty the size of the GMF you specify. 

In place of graphic map files, it is recarmended that you use external 
bitmap files. The external bitmap files are preferable in most cases. For 
a description of the routine for creating such files, see 
GFR_$OPEN_BITMAP_FILE in Chapter 11 of this manual. 
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12.1 INSERT FILES 

Pascal prograirs using any GfiF routines irust include the file 
/SYS/INS/BASE.INS.PAS and /SYS/lN^Off'.INS.PAS. PORERM prograrrs irust 

include /SYS/INS/BASE. INS. FTN and /SYS/INS/OIF. INS. FIN. Prograirs written in 
C irust include /SYS/INI^BASE. INS. C and /SYS/INS/GMF. INS. C. 

12.2 DATA STRUCTURES 

The GMF iranager does not define an^ new data structures. 

12.3 ERROR NESSAGES 



Here are the possible error messages generated b^ the GMF calls described in 
this chapter: 

GMF_$BAD_BPI — Bits/inch paraireter is negative 

GMF_$BAD_X_DIM — X dimension parameter is not positive 

GMF_$BAD_Y_DIM ~ Y dimension parsmneter is not positive 

GMF_$BADJWPL — V/ords/line parameter is too arall for the 

X dimension you specified 

GMF_$BAD_K)S — Opening position parameter is illegal 

GMF_$NOT_GMF ~ The file you wanted to open is not a GMF 



12.4 PROGRAMMING EXAMPLE 

This example in Pascal shows how to combine the calls described in this 
chapter with GPR calls (see Chapter 11) to form a typical GMF operation. 
This example restores a previously saved GMF. 

{Initialize the grajAiics primitive package in bor row-display mode.} 
gpr_$init (gpr_$borrow, 1, scsize, 0, disp_desc, sts); 

{ Get the starting pointer. } 
gpr_$inq_bitmap_pointer (disp_descr ptr, width, sts); 

{ Open the file. } 
gmf_$open { '//pepsi/adr/gmf /turbine . pad* ,27 , grf_$read, id, sts) ; 

{ Restore the screen. } 
grrf_$restore_plane (id, scsize. x_size, scsize.y_size,wpl,ptr ,bpi, sts) ; 
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{ Close the file. } 
girf _$cl ose ( idr status ) ; 

ExpianatJQn 

The call to GH^$INIT puts the screen in borrcw-displ^ irode. The next call 
obtains "ptr", the pointer to the start of the screen bitrrap. The call to 
G]yiF_$OPEN opens a GMF with the specified naire, returning the identification 
ty which you subsequently refer to the GMF. T3ie next call restores the 
screen f rar this GMF. (Alternatively, you can use a call here to copy a 
plane or subplane to the GMF. ) The final call closes the GMF. 



12.5 USER-CALLABLE ROUTINES 



The rarainder of this chapter specifies each call to the GMF iranager in 
al0iabetical order. 
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GMF_$aOSE 

GMF_$CLOSE — Qoses a GMF 

F O R M?VT 

GMF_$CLOSE (streair-idr status) 

INPUT P A R AMETgRS 

streair-id 

The streair-id of the GMF to be closed, in STREAJl_$ID_T format. This is 
a 2-byte integer. You obtain the streair-id f ror the call to GMF_$OPEN 
that you used to open the GMF. 

OUTPUT PARAMETERS 

status 

Goirpletion status, in STATOS_$T fonrat. 

N QTE g 

* To open a GMF, use GMF_$OPEN. 
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GMF_$(I)Py_ELME 



GMF_$O0py_ILME — Durps a rectangular area of bits f ror virtual irarory into 

a GMF. 



FORMA T 

GMF_$GOPY_HjME (streair-id, black-or-white, bpi, bit-pointer, x-diir, y-diir, 
wpl, status) 

INPUT PARAMETERS 

stream- id 

The streair-id of the GMF into which the image is to be stored, in 
STOEAn_$ID_T format. This is a 2-byte integer. You obtain the 
stream- id f ror the call to GMF_$OPEN that you used to open the GMF. 

bl ack-or-whi te 

A Boolean variable. A value of TFUE means "1" bits are black and "0" 
bits are white. A value of FALSE means "0" bits are white and "1" bits 
are black. Ihis information is stored in the GMF. 

bpi 

The number of bits per inch in the GMF. This information is also stored 
in the GMF. It indicates the physical density of the image represented 
in the GMF. If this parameter is nonzero, a device to which you output 
the GMF m^ compress or expand the image to produce a result which is as 
dose as possible to the image's original size. If this parameter is 
zero, an output device uses one dot to represent each bit f ror the GMF, 
regardless of the resulting physical size of the image. This is a 
2-byte integer. 

bit-pointer 

A pointer to the i5)per left corner of the rectangular area to be stored, 
in GMF_$MEiyDRY_PrR_T format. This is a 4-tYte integer. You obtain this 
value ty calling the routine GPiL$INQ_BITMAP_K)INTER. 

x-dim 

The X dimension of the rectangular area to be stored in the GMF. 

y-dim 

Ihe y dimension of the rectangular area to be stored in the GMF. 



wpl 



The nurber of 16-bit words per scan line in the GMF. The value of this 
parameter, which is stored in the GMF, is usually 64. By specifying a 
smaller value, you can produce a GMF that takes less storage space. 
However, the wpl must be at least 1/16 of the specified x-dim. For 
instance, if you are storing an area 400 bits wide in a GMF, the GMF 
must use at least 25 words to represent each scan line (row of dots). 
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GMF_$a)PY_HiME 



OUTPUT PARAMETERS 

Status 

GoirpLetion status, in STATOS_$T fonrat. 

NOTES 

* To store an iirage in a GMF, you irust have opened the GMF with the 
GMF_$OPEN call. 

* After storing an iirage in a GMF, dose the GMF with the GMF_$CLOSE 
call. 

* The GMF_$OOPY_H.ME call is a special case of the GMF_$GOP!CSUBELANE 
call. 
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GMF_$a)PY_SUBLANE 



GMF_$CDPY_SUBPLME — Durps a rectangular area of bits f rar virtual irenrory 

into a GMF. 



GMF_$CDPY_StBELME (streair-id, bLack-or-white, bpi, bit-pointer, x-diir, y-diir, 

x-offset, y-offset, wpi, status) 

streair-id 

The streair-id of the GMF into which the iirage is to be stored, in 
S1REAM_$ID_T fonrat. This is a 2-byte integer. You obtain the 
streair-id f ronr the call to GMF_$OPEN that you used to open the GMF. 

black-or-white 

A Boolean variable. A value of TE^E ireans "1" bits are black and "0" 
bits are white. A value of FALSE ireans "0" bits are white and "1" bits 
are black. Ihis inf onration is stored in the GMF. 

bpi 

Ihe nurrber of bits per inch in the GMF. This inf onration is also stored 
in the GMF. It indicates the physical density of the image represented 
in the GMF. If this paraireter is nonzero, a device to which you output 
the GMF ir^ coirpress or expand the iirage to produce a result which is as 
close as possible to the image's original size. If this parameter is 
zero, an output device uses one dot to represent each bit from the GMF, 
regardless of the resulting physical size of the image. 

bit-pointer 

A pointer to the upper left corner of the rectangular area to be 
stored. This is a four-byte integer. You obtain this value fcy calling 
the routine GPIl_$DiQ_BITMAP_POINTER. 

x-dim 

The X dimension of the rectangular area to be stored in the GMF. 

y-dim 

The y dimension of the rectangular area to be stored in the GMF. 

x-offset 

Ihe X starting position of the rectangular area to be stored in the 
GMF. 

y-offset 

Ihe y starting position of the rectangular area to be stored in the 
GMF. 
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GMF_$a)PY_SUBELANE 



wpL 



The nurber of 16-bit words per scan line in the GMF. Ohe value of this 
pararreter, which is stored in the GMF, is usually 64. By specifying a 
araller value, you can produce a GMF that takes less storage space. 
Hcwever, the wpl irust be at least 1/16 of the specified x-diir. For 
instance, if you are storing an area 400 bits wide in a GMF, the GMF 
must use at least 25 words to represent each scan line (rcw of dots). 



status 

Goirpletion status, in STAIUS_$T fonrat. 

NO TE S 

* To copy a plane into a GMF, you irust have opened the GMF with the 
GMF_$OPEN call. 

* After copying a plane into a GMF, dose the GMF with the GMF_$CLOSE 
call. 

* The GMF_$GOPY_SUBHiME call is a irore general forir of the 
GMF_$GOPY_H[iME call. 
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GMF_$OPEN 



GiyiF_$OPEN — Opens or creates a GMF. 

F OP M AT 

GMF_$OPEN (naire, naire- length, start, streair-id, status) 

INP UT vmm^BB 

naire 

Bathnaire, in NAME_$PNANE_T f onrat. 

naire-length 

The length of the naire. Ihis is a 2-byte integer. 

start 

Desired position in the file after open, in GMF_$OPOS_T f onrat. Ihis is 
a 2-byte integer. If you are opening the GMF to write data to it (to 
oofy a plane or subplane into it) , use one of these two constants: 

GMF_$APPEND — sets the initial position to EOF. 
GMF_$OV^EI^RITE — truncates the object to length and sets the initial 

position to the beginning. 

If you are opening the GMF to read data f ror it (restoring a plane) , use 
this constant: 

GMF_$READ — sets the initial position to the beginning without 

truncating the GMF. 

If the specified GMF does not exist and you used GMF_$OPEN to create it, 
it does not Fatter what value this parameter has. 



streair-id 

The streair-id of the opened GMF, in STREAH_$ID_T f onrat. This is a 
2-byte integer. You use this value in subsequent GMF calls that refer 
to the opened GMF. 

status 

Coirpletion status, in STMUS_$T f onrat. 
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GiyiF_$OEEN 

NQTEig 

* If the specified GMF does not exist, the call to GMF_$OPEN creates it. 

* You irust call GMF_$OPEN before trying to read or write a GMF. 

* After opening a GMF with GMF_$OPEN, you irust eventually dose it ty 
calling GMF_$CLOSE. 
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GMF_$RESTORB_ELME 



GMF_$RESTORELHjME — Copies an iirage back to the screen f rorr a GMF. 
GMF_$RES'rDRELHiME (streair-id, x-diir, y-diir, wpl, start, bpi, status) 

streair~id 

The streair-id of the GMF which is to supply the iirage, in 

ST[REAM_$ID_T fonrat. Ohis is a 2-byte integer. You obtain 

this paraireter f rar the call to GMF_$OPEN you used to open the GMF. 

x-diir 

The x-diirension in bits of the display to which an iirage is to be restored. 
This is a 2-byte integer. 

y-diir 

The y-diirension in bits of the display to which an iirage is to be restored. 
This is a 2-byte integer. 

wpl 

The nurber of 16-bit words in the x-diirension in the destination bitonap. 
This is a 2-byte integer. 

start 

The starting address in the destination bitirap. 



OUTPUT PARAMETERS 

tpi 

Bits per inch as specified in GMF_$GOPy_H:jANE. 

status 

Goirpletion status, in STAIUS_$T fonrat. 



NOTES 

* Before calling GMF_$RESTDR^HiME, you irust use GPR_$INIT to place the 
node in 

borrcw-displ^ irode. 

* The size of the area to be restored is the saire as the size of the 
area you originally copied into the GMF. This inf onration is contained 
in the GMF. 
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GiyiF_$RES1DRELrLME 



* The area to be restored is determined ty the bit-pointer specified 
in the GMF_$RESTORELHiME call and the size data in the GMF. If 
this area runs off the right side or the bottar of the screen, 

the GMF iranager restores only the portion of the stored iirage that 
fits on the screen. 

* To restore a plane f ror a GMF, you irust have opened the GMF 
with the GMF_$OPEN call. 

* After restoring a plane f ror a GMF, you should close the GMF with the 
GMF_$CLOSE call. 
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APPENDIX A 
KEYBOARD CHARTS 



The following two charts and figures give the 8-bit ASCII values generated 
for two DOMAIN keyboards: 880 and low-profile. These charts include 
characters used in keystroke events. The columns represent the four highest 
order bits of an 8-bit value. The rows represent the four lowest order bits 
of an 8-bit value. For a more complete description of conventions for naming 
keys, see the DOMAIN System Command Reference Manual . 
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Figure A-1. Low^Profile keyboard Chart - Translated (user mode) 
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Figure A-2, Low-Profile Keyboard 
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Figure A-3. 880 Keyboard 
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Figure A-4. 880 Keyboard Chart - Translated (user mode) 
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Appendix A 



APPENDIX B 
INSERT FILE FOR PASCAL 



ahis appendix contains the insert file for Pascal. This file includes 
error messages, color values, data types, and data structures. For 
a listing of data types and data structures in a table format, see 
Chapter 9. 



CONST 



gpr 
gpr 
gpr 
gpr 
gpr. 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr- 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 
gpr 



.$operation_ok = 16 00000000 

.$not_initialized = 16 06010001 

.$alrea^_initialized = 16 06010002 

.$v/rong_display_hardware = 16 06010003 

.$illegal_for_frame = 16 06010004 

.$must_borrow_display = 16 06010005 

.$no_attributes_defined = 16 06010006 

.$no_more_space = 16 06010007 

.$dimension_too_big = 16 06010008 

.$dimension_too_small = 16 06010009 

.$bad_bitmap = 16 0601000A 

.$bad_attribute_block = 16 0601000B 

.$window_out_of_bounds = 16 0601000C 

.$source_out_of_bounds = 16 0601000D 

.$dest_out_of_bounds = 16 0601000E 

.$invalid_plane = 16 0601000F 

.$cant_deallocate = 16 06010010 

.$coord_out_of_bounds = 16 06010011 

_$invalid_color_map = 16 06010012 

.$invalid_raster_op = 16 06010013 

.$bitmap_is_read_only = 16 06010014 

$internal_error = 16 06010015 

$font_table_full = 16 06010016 

$bad_font_file = 16 06010017 

.$invalid_font_id = 16 06010018 

.$window_obscured = 16 06010019 

.$not_in_direct_mode = 16 0601001A 

$not_in_polygon = 16 0601001B 

.$kbd_not_aoq = 16 0601001C 

_$display_not_aoq = 16 0601001D 

.$illegal_j)ixel_values = 16 0601001E 
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CONST 



TYPE 



gpr_$il legal_when_imaging 

gpr_$inval id_iiiaging_f ormat 

gpr_$must_release_display 

gpr_$cant_mix_nK)des 

gpr_$no_input_enabled 

gpr_$duplicate_points 

gpr_$array_not_sorted 

gpr_$char acte r_not_in_f ont 

gpr_$illegal_f ill_pattern 

gpr_$illegal_fill_scale 

gpr_$incor rect_al igninent 

gpr_$illegal_text_path 

gpr_$unabl e_to_rotate_f ont 

gpr_$font_is_read_only 

gpr_$illegaljpattern_length 



16 0601001F 
16 06010020 
16 06010021 
16 06010022 
16 06010023 
16 06010024 
16 06010025 
16 06010026 
16 06010027 
16 06010028 
16 06010029 
16 0601002A 
16 0601002B 
16 0601002C 
16 0601002D 



gpr_$black 

gpr_$white 

gpr_$red 

gpr_$green 

gpr_$blue 

gpr_$CYan 

gpr_$magenta 

gpr_$yellov/ 

gpr_$transparent 

gpr_$background 



= 0; 

= 16 FFFFFF; 
= 16 FFOOOO; 
= 16 OOFFOO; 
= 16 OOOOFF; 
= 16 OOFFFF; 
= 16 FFOOFF; 
= 16 FFFFOO; 

= -1; 

= -2; 



gpr_$string_size = 256 
gpr_$max_x_size = 4096 
gpr_$max_y_size = 4096 
gpr_$highest_plane = 7 
gpr_$nil_attr ibute_desc 



= 0; 



gpr_$nil_bitmap_desc = 0; 

gpr_$niax_fcHiif_group = 0; 
gpr_$binf_inajor_version = 1; 
gpr_$binf_minor_version = 1; 



color value for black } 

color value for white } 

color value for red } 

color value for green } 

color value for blue } 

color value for cyan (blue + green) } 

color value for magenta (red + blue) } 

color value for yellow (red + green) } 

pixel value for transparent 

(no change) } 

pixel value for window background } 

nuinber of chars in a gpr string } 
max bits in bitmap x dimension } 
max bits in bitmap y dimension } 
max plane number in a bitmap } 
value of a descriptor of 
nonexistent attributes } 
value of a descriptor of a 
nonexistent bitmap } 
max group in external bitmaps } 



{ the five ways to use this package } 
gpr_$display_mode_t = (gpr_$borrowr 

gpr_$frame, 
gpr_$no_display , 
gpr_$direct, 
gpr_$bor row_nc 
); 

{ possible display hardware configurations } 
gpr_$display_config_t = (gpr_$bw_800xl024, 
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gpr_$bwL.1024x800 , 
gpr_$color_1024xl024x4 , 
gpr_$color_1024xl024x8, 
gpr_$RESEFVEDx4 , 
gpr_$RESERVEDx8 

); 

{ iitaging vs interactive display formats } 
gpr_$iitaging_fonnat_t = (gpr_$ interactive, 

gpr_$imaging_1024xl024x8 , 
gpr_$imaging_51 2x51 2x24 
); 

{ input event types } 
gpr_$event_t = ( gpr_$keystroke, gpr_$buttons, gpr_$locator , 
gpr_$entered_window, gpr_$lef t_window , 
gpr_$locator_stop, gpr_$no_event ) ; 

{ sets of key values for input events } 
gpr_$keyset_t = SET OF char; 

{ options for aoqui re-display behavior when window is obscured } 
gpr_$obscured_opt_t = ( gpr_$ok_if_obs, gpr_$error_if_obs, 

gpr_$pop_if_obs, gpr_$block_if_obs ) ; 

{ eventcount keys } 
gpr_$ec_key_t = (gpr_$input_ec) ; 

{ procedure type for refresh-window procedures } 
gpr_$rwin_pr_t = ''pkx:edurE( IN unobscured: boolean; 

IN pos_change: boolean ); 

{ procedure type for ref reshr-hidden display memory procedures } 
gpr_$rhdm_pr_t = "PRXEDURE; 

{ bitmap coordinates } 
gpr_$coordinate_t = integerl6; 

{ lists of bitmap coordinates } 
gpr_$coordinate_array_t = ARRAY [1..10] OF gpr_$coordinate_t; 

{ bitmap positions } 
gpr_$position_t = RECORD 

x_coord, y_coord: gpr_$coordinate_t 
END; 

{ bitmap offsets } 
gpr_$off set_t = RECX)RD 

x_size, y_size: gpr_$coordinate_t; 
END; 

{ windows on a bitmap } 
gpr_$window_t = RECORD 
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window_base : gpr_$position_t; 
window_size: gpr_$offset_t 
END; 

{ lists of windows } 
gpr_$window_list_t = ARRAY [1.. 10] OF gpr_$window_t; 

{ horizontal line segments } 
gpr_$horiz_seg_t = REODRD 

x_coord_l, x_coord_r, y_coord: gpr_$coordinate_t 
END; 

{ trapezoids with horizontal bases: defined as 2 horizontal 
line segments, top and bottom } 
gpr_$trap_t = RECORD 

top, bot: gpr_$horiz_seg_t 
END; 

{ lists of trapezoids with horizontal bases } 
gpr_$trap_list_t = ARRAY [1..10] OF gpr_$trap_t; 

{ graphics primitive strings } 
gpr_$string_t = ARRAY [l..gpr_$string_size] OF char ; 

{ bitmap plane numbers } 
gpr_$plane_t = . . gpr_$highest_plane ; 

{ bitmap plane masks } 
gpr_$mask_t = SET OF gpr_$plane_t; 

{ color values } 
gpr_$color_t = linteger; 

{ pixel values } 
gpr_$pixel_value_t = linteger; 

{ arrays of color values } 
gpr_$color_vector_t = ARRAY [0..255] OF gpr_$color_t; 

{ arrays of pixel values } 
gpr_$pixel_array_t = ARRAY [0.. 131072] OF gpr_$pixel_value_t; 

{ raster operation opcodes } 
gpr_$raster_op_t = 0..15; 

{ arrays of raster operation opcodes } 
gpr_$raster_op_array_t = ARRAY [gpr_$plane_t] OF gpr_$raster_op_t; 

{ scalar type for directions } 
gpr_$direction_t = (gpr_$up, gpr_$down, gpr_$left, gpr_$right) ; 

{ line drawing styles } 
gpr_$linestyle_t = (gpr_$solid, gpr_$dotted) ; 



i^pendix B B-4 



gpr_$line_pattern_t = ARRAY [1..4] OF integer; 

{ attribute block descriptors } 
gpr_$attribute_desc_t = linteger; 

{ bitmap descriptors } 
gpr_$bitinap_desc_t = linteger; 

{ external bititap header version number } 
gpr_$version_t = 
RECORD 

major : integerl6; 
minor : integerl6 
END; 

{ external bitmap group header descriptor } 
gpr_$bnif_group_header_t = 
RECDRD 



n_sects 

pixel_size 

allocated_size 

by tes_pe r_line 

by tes_pe r_sect 

storage_offset 

END; 



integerl6 ; 
integerl6 ; 
integerl6; 
integerl6 ; 
integer32 ; 
univ_ptr ; 



{ array of external bitmap group header descriptors } 
gpr_$bmf_group_header_array_t = 

ARRAY [O..gpr_$max_bmf_group] OF gpr_$bmf_group_header_t; 

{ ways to access external bitmap objects } 
gpr_$access_mode_t = (gpr_$create,gpr_$update, gpr_$write, 

gpr_$readonly) ; 
%eject; 
{ Initialization and termination. } 



{ GPR_$INIT initializes the graphics primitive package. } 

PROCEDURE gpr_$init ( 

IN op: gpr_$display_mode_t; { mode of operation } 

IN unit_or_pad: stream_$id_t; { display unit or stream id 

of dm pad if any } 
IN size: gpr_$offset_t; { disp bitmap sizes in bits for 

X and y } 
IN hi_plane: gpr_$plane^t; { highest plane number display 

bitmap is to have } 
OUT init_bitmap: gpr_$bitmap_desc_t; { descriptor of initial 

bitmap } 
OUT status: status_$t { returned status } 
); EXTERN; 
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{ GPR_$TERMINATE terminates this package's operation. } 

PROCEDURE gpr_$tenninate ( 

IN delete_disp: boolean; { whether to delete dm frame } 
OUT status: status_$t { returned status } 
); EXTERN; 

%eject; 

{ Set and inquire operations for the display. } 



{ GPR_$INQ_GONFIG returns the current display configuration. } 

PROCEEXJRE gpr_$inci_oonfig ( 

OUT oonf ig: gpr_$display_conf ig_t; 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_cr)LOR_MAP gives new values for the color map. } 

PROCEDURE gpr_$set_color_map ( 

IN start_index: gpr_$pixel_value_t; { index of first entry } 
IN n_entries: integer; { of entries } 
IN v: UNIV gpr_$color_vector_t; { entry values } 
OUT status: status_$t { returned status } 
) ; EXTERN; 



{ GPR_$INQ_GOLOR_MAP returns current values in the color map. } 

PROCEDURE gpr_$inq_color_map ( 

IN start_index: gpr_$pixel_value_t; { index of first entry } 
IN n_entries: integer; { of entries } 
OUT v: UNIV gpr_$color_vector_t; { entry values } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_CURSOR_PATTERN loads a cursor pattern. } 

PROCEDURE gpr_$set_cursor_jattern ( 

IN cursor: gpr_$bitmap_desc_t;{ pattern for cursor } 
OUT status: status_$t { returned status } 
); EXTERN; 
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{ GPR_$SET_ajRSOR_ACTIVE specifies whether the cursor should be 
on or off. } 

PROCEDURE gpr_$set_cursor_active ( 

IN active: boolean; { false — > off, true — > on } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_CURSOR_P0SITION gives the position at which the cursor is 
to be displayed, in the current bitmap. } 

PROCEDURE gpr_$set_cursor_position ( 

IN pos: gpr_$position_t; { where it goes } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_CURSOR_ORIGIN gives the cursor-relative position of its pixel 
which is to be placed at the cursor position. } 

PROCEDURE gpr_$set_cursor_origin ( 

IN origin: gpr_$position_t; { the position of the cursor 

pixel } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_CURSOR returns information about the cursor. } 

PROCEDURE gpr_$inq_cursor ( 

OUT cursor: gpr_$bitmap_desc_t; { pattern for cursor } 

OUT ops: gpr_$raster_op_array_t; { raster ops for cursor } 

OUT active: boolean; { whether cursor is active } 

OUT pos: gpr_$position_t; { current cursor position } 

OUT origin: gpr_$position_t; { current cursor origin } 
OUT status: status_$t { returned status } 
) ; EXTERN; 



{ GPR_$WAIT_FRAME causes the color display hardware to defer processing 
further requests until the next end-of-frame. } 

PROCEDURE gpr_$wait_frame ( 

OUT status: status_$t { returned status } 
); EXTERN; 
%eject; 
{ Bitmap control functions. } 
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{ GPR_$SET_BMMAP establishes the current bitmap for subsequent 
operations. } 

PROCEDURE gpr_$set_bitinap ( 

IN bitmap: gpr_$bitmap_desc_t; { the given bitmap } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_BiaMAP returns a descriptor of the current bitmap. } 

PROCEDURE gpr_$inq_bitmap ( 

OUT bitmap: gpr_$bitmap_desc_t; { the current bitmap } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$ALL0CATE_BI1MAP allocates a bitmap in main memory. } 

PROCEDURE gpr_$allocate_bitmap ( 

IN size: gpr_$offset_t; { sizes in bits for x and y } 
IN hi_plane: gpr_$plane_t; { highest plane number bitmap is 

to have } 
IN attr: gpr_$attribute_desc_t; { attributes it is to have } 
OUT bitmap: gpr_$bitmap_desc_t; { the bitmap returned } 
OUT status: status_$t { returned status } 
) ; EXTERN; 



{ GPR_$ALLOCATE_BnMAP_NC allocates a bitmap in main memory without 
zeroing it. } 

PROCEDURE gpr_$allocate_bitmap_nc ( 

IN size: gpr_$offset_t; { sizes in bits for x and y } 
IN hi_plane: gpr_$plane_t; { highest plane number bitmap 

is to have } 
IN attr: gpr_$attribute_desc_t; { attributes it is to have } 
OUT bitmap: gpr_$bitmap_desc_t; { the bitmap returned } 
OUT status: status_$t { returned status } 
); EXTERN; 

{ GPR_$ALLOCATE_HDM_BITiyiAP allocates a bitmap in hidden_display memory. } 

PROCEDURE gpr_$allocate_hdm_bitmap ( 

IN size: gpr_$offset_t; { sizes in bits for x and y } 
IN hi__plane: gpr_$plane_t; { highest plane number bitmap is 

to have } 
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IN attr: gpr_$attribute_desc_t; { attributes it is to have } 
OUT bitmap: gpr_$bitinap_desc_t; { the bitmap returneca } 
OUT status: status_$t { returnecJ status } 
); EXTERN; 



{ GPR_$0PEN_BI1MAP_FILE obtains access to an external bitmap } 
PROCEDURE gpr_$open_bitmap_file ( 



IN 
IN 


access 
filename 


IN 

IN OUT 
IN OUT 
IN OUT 
IN OUT 
IN 


namesize 

version 

size 

groups 

g_headers 

attribs 


OUT 


bitmap 


OUT 


created 


OUT 
); EXTERN; 


status 



gpr_$access_mo(ae_t ; 
UNIV name_$pname_t; 



{ pathname of bitmap 

file } 
{ length of file name } 



{ x,y size of bitmap } 



integer; 

gpr_$ver sion_t ; 

gpr_$offset_t; 

integer; 

gpr_$bmf_group_header_array_t; 

gpr_$attribute_desc_t; { attributes bitmap is 

to have } 
gpr_$bitmap_desc_t; { returned bitmap 

descriptor } 
boolean; { TE^E if GPR created 

the file } 
status_$t 



{ GPR_$DEMiLOCATE_BITMAP deallocates a bitmap allocated by 
ALL0CATE_BI1MAP. } 

PROCEDURE gpr_$deallocate_bitmap ( 

IN bitmap: gpr_$bitmap_desc_t; { the bitmap to kill } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_BnMAP_POINTER returns a pointer to the storage/display memory 
for the given bitmap and the number of words each scan line occupies. 
This information can be used to directly manipulate the bits in the bitmap. 

PROCEDURE gpr_$inq_bitmap_pointer ( 

IN bitmap: gpr_$bitmap_desc_t; { the given bitmap } 
OUT storage_ptr: univ_ptr; { the address of storage } 
OUT line_width: integer; { number of 16-bit words per line } 
OUT status: status_$t { returned status } 
); EXTERN; 



GPR_$INQ_BM_BIT_OFFSET returns the number of bits in the most significant 

part of the first word of each scanline which are not part of the 

given bitmap. In other words, the offset is the number of bits between 
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a 16-bit word boundary and the left edge of the bitmap. 

Currently, this number can only be nonzero for direct graphics bitmaps. } 

PROCEDURE gpr_$inq_bm_bit_offset ( 

IN bitmap: gpr_$bitmap_desc_t; { the given bitmap } 
OUT bit_offset: integer; { in the range to 15 } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SELECT_OOLOR_FRAiyiE selects whether frame (top 1024 lines) or 
frame 1 (bottom 1024 lines) is visible. Normally frame is visible. } 

PROCEDURE gpr_$select_color_frame ( 

IN frame: integer; { or 1 } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$REMAP_0OLOR_MEM0RY sets the plane of frame of color display memory 
(normally visible) which is mapped at the address returned by 
INQ_BI'IMAP_POINTER. } 

PROCEDURE gpr_$rQnnap_color_memory ( 

IN plane: gpr_$plane_t; { plane for access thru storage_ptr } 
CUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$REMAP_00L0R_MEM0RY_1 sets the plane of frame 1 of color display 
memory (normally hidden) which is napped at the address returned by 
INa-BiaMAP.POINTER. } 

PROCEDURE gpr_$remap_color_memory_l ( 

IN plane: gpr_$plane_t; { plane for access thru storage_ptr } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$COIiOR_ZOOM sets the zoom scale factors for the color display. } 

PROCEDURE gpr_$color_zoom ( 

IN X, y: integer; { 1 to 16 } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$ENABLE_DIRECT_ACCESS waits for display hardware to finish current 
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operations so that the user can access display memory directly. } 

PROCEDURE gpr_$enable_direct_access ( 

OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_BITMAP_J)IMENSIONS changes the size and number of planes 
of the given bitmap. } 

PROCEDURE gpr_$set_bitmap_diinensions ( 

IN bitmap: gpr_$bitmap_desc_t; { the given bitmap } 

IN size: gpr_$offset_t; { new sizes in bits for x and y } 

IN hi_plane: gpr_$plane_t; { new highest plane number for 

bitmap } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_BITMAP_DIMENSIONS returns the size and number of planes 
of the given bitmap. } 

PROCEDURE gpr_$inq_bitmap_dimensions ( 

IN bitmap: gpr_$bitmap_desc_t; { the given bitmap } 
OUT size: gpr_$offset_t; { sizes in bits for x and y } 
OUT hi_plane: gpr_$plane_t; { highest plane number bitmap has } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$ALLOCATE_ATTRIBUaE_B[iOCK allocates an attribute block, 
initialized to default settings. } 

PROCEDURE gpr_$allocate_attribute_block ( 

OUT attrib: gpr_$attribute_desc_t; { new attribute block } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$DEALiLOCATE_ATTRIBUTE_BLOCK deallocates an attribute block allocated 
by ALLOCATE_ATrRIBUTE_BLOCK. } 

PROCEDURE gpr_$deallocate_attribute_block ( 

IN attrib: gpr_$attribute_desc_t; { attribute block to be 

deleted } 
OUT status: status_$t { returned status } 
); EXTERN; 
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{ GPR_$SET_ATTRIBUTE_BLOCK establishes the given attributes as the attributes 
of the current bitmap. } 

PIOCEDURE gpr_$set_attribute_block ( 

IN attrib: gpr_$attribute_desc_t; { new current attribute 

block } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$ATTRIBUTE_BIiOCK returns as the function value a descriptor of 
the attributes of the given bitinap. } 

FUNCTION gpr_$attribute_block ( 

IN bitmap: gpr_$bitmap_desc_t; { the bitmap with the 

attributes wanted } 
OUT status: status_$t 
) : gpr_$attribute_desc_t; EXTERN; 
%eject; 
{ Set and inquire operations for bitmap attributes. } 



{ GPR_$SET_attribute sets an attribute in the current bitmap. 
The list of calls follows. } 



PROCEDURE gpr_$set_clip_window ( 

IN window: gpr_$window_t; 
OUT status: status_$t 
); EXTERN; 

PROCEDURE gpr_$set_clipping_active ( 
IN active: boolean; 
OUT status: status_$t 
); EXTERN; 

PROCEDURE gpr_$set_text_font ( 

IN font_id: integer; 
OUT status: status_$t 
); EXTERN; 

PROCEDURE gpr_$set_text_path ( 

IN path: gpr_$direction_t; 
OUT status: status_$t 
); EXTERN; 

PROCEDURE gpr_$set_coordinate_origin ( 

IN origin: gpr_$position_t; 
OUT status: status_$t 
); EXTERN; 



new clipping window } 
returned status } 



false — > off, true — > on } 
returned status } 



new text font } 
returned status } 



text path } 
returned status } 



new coordinate origin } 
returned status } 
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PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



gpr_$set_plane_mask ( 

IN mask: gpr_$mask_t; 
OUT status: status_$t 

); EXTERN; 

gpr_$set_draw_value ( 

IN val: gpr_$pixel_value_t; 

OUT status: status_$t 
); EXTERN; 

gpr_$set_text_value ( 

IN val: gpr_$pixel_value_t; 

OUT status: status_$t 
); EXTERN; 

gpr_$set_text_background_value ( 
IN val: gpr_$pixel_value_t; 
OUT status: status_$t 

) ; EXTERN; 

gpr_$set_fill_value ( 

IN val: gpr_$pixel_value_t; 

OUT status: status_$t 
); EXTERN; 

gpr_$set_fill_background_value ( 
IN val: gpr_$pixel_value_t; 
OUT status: status_$t 

); EXTERN; 

gpr_$set_fill_pattem ( 

IN pattern: gpr_$bitmap_desc 

IN scale: integer; 

OUT status: status_$t 
); EXTERN; 

gpr_$set_raster_op ( 

IN plane: gpr_$plane_t; 
IN op: gpr_$raster_op_t; 
OUT status: status_$t 

); EXTERN; 

gpr_$set_linestyle ( 

IN style: gpr_$linestyle_t; 

IN scale: integer; 

OUT status: status_$t 
); EXTERN; 



gpr_$set_line_pattern ( 

IN repeat_count: integer; 
IN pattern: gpr_$line_pattern 
IN length: integer; 
OUT status: status_$t 



new plane mask } 
returned status } 



new line-drawing value } 
returned status } 



new text value } 
returned status } 



new text background value } 
returned status } 



new fill value } 
returned status } 



new fill background value } 
returned status } 



■_t; { bitmap containing tile } 
scale factor for tile } 
returned status } 



plane for new raster op } 
new raster op } 
returned status } 



new line style } 

scale factor for dashes } 

returned status } 



scale factor } 

t_t; 

number of pattern bits } 

returned status } 
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); EXTERN; 



PROCEDURE 



PROCEDURE 



PROCEDURE 



gpr_$set_character_width ( 

IN font_id: integer; 

IN character: char; 

IN width: integer; 

OUT status: status_$t 
); EXTERN; 



{ f ont_id } 

{ character to modi:fy } 

{ new width } 

{ returned status } 



gpr_$set_horizontal_spacing ( 

IN font_id: integer; { font_id } 

IN horizontal_spacing: integer; { new horiz-spacing } 

OUT status: status_$t { returned status } 

); EXTERN; 



gpr_$set_space_size ( 
IN font_id: integer; 
IN space_size: integer; 
OUT status: status_$t 

); EXTERN; 



{ font_id } 

{ new space-size } 

{ returned status } 



GPR_$INQ_attributes returns the current settings of a group 
of attributes for the current bitinap. } 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



PROCEDURE 



gpr_$inq_constraints ( 

OUT window: gpr_$window_t; 

OUT active: boolean; 

OUT mask: gpr_$mask_t; 

OUT status: status_$t 
); EXTERN; 



{ clipping window } 

{ whether clipping is active } 

{ plane mask } 

{ returned status } 



gpr_$inq_text ( 

OUT font_id: integer; { font id } 

OUT path: gpr_$direction_t; { text path } 

OUT status: status_$t { returned status } 

); EXTERN; 



gpiL_$inq_text_path ( 

OUT path: gpr_$direction_t; 

OUT status: status_$t 
); EXTERN; 



{ text path } 

{ returned status 



gpr_$ini:i_coordinate_origin ( 

OUT origin: gpr_$position_t; { the coordinate origin } 
OUT status: status_$t { returned status } 

); EXTERN; 

gpr_$inq_draw_value ( 

OUT val: gpr_$pixel_value_t; { line-drawing value } 
OUT status: status_$t { returned status } 

); EXTERN; 
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PROCEDURE gpr_$inq_text_values ( 

OUT tval: gpr_$pixel_value_t; { text value } 
OUT bval: gpr_$pixel_value_t; { text background value } 
OUT status: status_$t { returned status } 
); EXTERN; 

PROCEDURE gpr_$inq_fill_value ( 

OUT val: gpr_$pixel_value_t;{ fill value } 
OUT status: status_$t { returned status } 
); EXTERN; 

PROCEDURE gpr_$inq_fill_background_value ( 

OUT val: gpr_$pixel_value_t;{ new fill background value } 
OUT status: status_$t { returned status } 
); EXTERN; 

PROCEDURE gpr_$incL_fill_pattern ( 

OUT pattern: gpr_$bitinap_desc_t; { bitmap containing tile } 
OUT scale: integer; { scale factor for tile } 
OUT status: status_$t { returned status } 
); EXTERN; 

PROCEDURE gpr_$inq_raster_ops ( 

OUT ops: gpr_$raster_op_array_t; { raster ops for all 

planes } 
OUT status: status_$t { returned status } 
); EXTERN; 

PROCEDURE gpr_$irx3_linestyle { 

OUT style: gpr_$linestyle_t; { line style } 
OUT scale: integer; { scale factor for dashes } 
OUT status: status_$t { returned status } 
); EXTERN; 

PROCEDURE gpr_$inq_line_j)attern ( 

OUT repeat_count: integer; { scale factor } 
OUT pattern: gpr_$line_pattern_t; 

OUT length: integer; { number of pattern bits } 
OUT status: status_$t { returned status } 
); EXTERN; 



PROCEDURE gpr_$inq_character_width ( 
IN font_id: integer; 
IN character: char; 
OUT width: integer; 
OUT status: status_$t 
); EXTERN; 



{ font id} 

{ specified character } 
{ width of character } 
{ returned status } 



PROCEDURE gpr_$inq_horizontal_spacing ( 

IN font_id: integer; { font id} 
OUT horizontal_spacing: integer; { horiz spacing } 
OUT status: status_$t { returned status } 
); EXTERN; 
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PROCEDURE gpr_$inq_space_size ( 

IN font_id: integer; { font id} 
OUT space_size: integer; { space size } 
OUT status: status_$t { returned status } 
); EXTERN; 

%eject; 

{ Drawing operations. } 



{ GPR_$MOVE sets the CP to the given position. } 

PROCEDURE gpr_$move ( 

IN X, y: gpr_$coordinate_t; { where to go } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_CP returns the current position. } 

PROCEDURE gpr_$inq_cp ( 

OUT X, y: gpr_$coordinate_t; { x and y of current position } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$LINE draws a line from the CP to the given position 
and sets the CP to the given position. } 

PROCEDUI^ gpr_$line ( 

IN X, y: gpr_$coordinate_t; { where to draw line to } 
OUT status: status_$t { returned status } 
) ; EXTERN; 



{ GPR_$POLYLINE does a series of LINEs, starting from the CP. } 

PROCEDURE gpr_$polyline ( 

IN X, y: UNIV gpr_$coordinate_array_t; { the list of 

endpoints } 
IN ipoints: integer; { how many } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$MULTILINE does a series of alternate MOVEs and LINEs. } 
PROCEDURE gpr_$multiline ( 
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IN X, y: UNIV gpr_$coordinate_array_t; { the list of 

endpoints } 
IN npoints: integer; { how many } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$DRAW_BOX draws a rectangular box } 

PROCEDURE gpr_$draw_box ( 

IN xl,yl,x2,y2 : gpr_$cx>ordinate_t; { corners } 
OUT status : status_$t { returned status } 
); EXTERN; 

{ GPR_$ARC_3P draw an arc from current point through t^vo points p2 and p3. } 

PROCEDURE gpr_$arc_3p ( 

IN p2: gpr_$position_t; { second point on the arc } 
IN p3: gpr_$position_t; { third point on the arc } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$CIRCLE draws a circle of radius around point center. } 

PROCEDURE gpr_$circle ( 

IN center: gpr_$position_t; { center of circle } 
IN radius: integer; { radius of circle } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$CIRCLE_FILLED draws a filled circle of radius around point center. } 

PROCEDURE gpr_$circle_filled ( 

IN center: gpr_$position_t; { center of circle } 
IN radius: integer; { radius of circle } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SPLINE_CUBIC_P draws a parametric cubic spline through the 
control points. } 

PROCEDURE gpr_$spline_cubic_p ( 

IN X, y: UNIV gpr_$coordinate_array_t; { list of control 

points } 
IN npoints: integer; { number of points } 
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OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SPLnffi_CUBIC_X draws a cubic spline as a function of x through the 
control points. } 

PROCEDURE gpr_$spline_cubic_x ( 

IN X, y: UNIV gpr_$coordinate_array_t; { list of control 

points } 
IN npoints: integer; { number of points } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$SPLINE_CUBIC_Y draws a cubic spline as a function of y through 
the control points. } 

PROCEDURE gpr_$spline_cubic_y ( 

IN X, y: UNIV gpr_$coordinate_array_t; { list of control 

points } 
IN npoints: integer; { number of points } 
OUT status: status_$t { returned status } 
); EXTERN; 
%eject; 
{ Tfext operations. } 



{ GPR_$LQAD_PCMLFILE loads a font contained in a file into an appro- 
priate area (based on the current display mode and configuration) . } 

PROCEDURE gpr_$load_font_file ( 

IN pn: UNIV name_$pname_t; { pathname of file } 

IN pnlen: integer; { pathname length } 

OUT font_id: integer; { returned font id } 

OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$UNLOAD_FCaw_FILE unloads a font that has been loaded by 
LOAD_PONT_FILE. } 

PROCEDURE gpr_$unload_font_file ( 

IN font_id: integer; { font id, from load_font_file } 
OUT status: status_$t { returned status } 
); EXTERN; 
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{ GPR_$TEXT writes text to a bitmap from the current position ("CP"). } 

PROCEDURE gpr_$text ( 

IN str: UNIV gpr_$string_t; { the string to write } 
IN strl: integer; { how long it is } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_1EXT_EXTENT returns the x- and y-offsets the given string 
would span if written with TEXT. } 

PROCEDURE gpr_$inc[_text_extent ( 

IN str: UNIV gpr_$string_t; { the string to be inquired 

about } 
IN strl: integer; { how long it is } 
OUT size: gpr_$offset_t; { how big it would be } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_TEXT_0FFSET returns the x- and y-offsets that must be added 
to the coordinates of the desired upper left pixel of the string to 
give the pixel from which the TEXT call should be made, and the 
X- or y-off set of the pixel which would be the updated CP. } 

PROCEDURE gpr_$inq_text_offset ( 

IN str: UNIV gpr_$string_t; { the string to be inquired 

about } 
IN strl: integer; { how long it is } 
OUT start: gpr_$offset_t; { where it would start relative 

to upper left pixel of string } 
OUT xy_end: integer; { where next write would start 

relative to same in x or y} 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$REPLICATE_FONT creates and loads a rea^write copy of the original 
font. } 

PROCEDURE gpr_$replicate_font ( 

IN font_id: integer; { original font id } 
OUT repl_font_id: integer; { replicated font id } 
OUT status: status_$t { returned status } 
) ; EXTERN; 

%eject; 

{ Data transfer operations. } 
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{ GPR_$CIiEAR clears the current bitmap to a given pixel value. } 

PROCEDURE gpr_$clear ( 

IN val: gpr_$pixel_value_t; { value to set whole bitmap to } 
OUT status: status_$t { returned status } 
) ; EXTERN; 



{ GPR_$READ_PIXELS reads the pixels from the given window of the current 
bitmap and stores them in a pixel array. } 

PROCEDURE gpr_$read_pixels ( 

IN src_w: gpr_$window_t; { the source window } 
OUT pix: UNIV gpr_$pixel_array_t; { the pixel array } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_^^RITE_PIXELS writes the pixels from a pixel array into the given 
window of the current bitmap. } 

PROCEDURE gpr_$write_pixels ( 

IN pix: UNIV gpr_$pixel_array_t; { the pixel array } 
IN dst_w: gpr_$window_t; { the destination window } 
OUT status: status_$t { returned status } 
); EXTERN; 

%eject; 

{ BLT operations. } 



{ GPR_$PIXEl4_BLT moves a rectangle of whole pixels from the source 
bitmap to a position in the current bitmap. } 

PROCEDURE gpr_$pixel_blt ( 

IN src_b: gpr_$bitmap_desc_t; { the source bitmap } 
IN src_w: gpr_$window_t; { the source window } 
IN dst_o: gpr_$position_t; { the destination origin 

(in current bitmap) } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$BIT_BLT moves a rectangle of bits from a plane of the source 
bitmap to a position in a plane of the current bitmap. } 

PROCEDURE gpr_$bit_blt ( 

IN src_b: gpr_$bitmap_desc_t; { the source bitmap } 
IN src_w: gpr_$window_t; { the source window } 
IN src_p: gpr_$plane_t; { the source plane } 
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IN dst_o: gpr_$position_t; { the destination origin } 

IN dst_p: gpr_$plane_t; { the destination plane } 

OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$ADDITIVE_BLT moves a rectangle of bits from a plane of the source 
bitmap to a position in every plane of the current bitmap. } 

PROCEDURE gpr_$additive_blt ( 

IN src_b: gpr_$bitmap_desc_t; { the source bitmap } 
IN src_w: gpr_$window_t; { the source window } 
IN src_p: gpr_$plane_t; { the source plane } 
IN dst_o: gpr_$position_t; { the destination origin } 
OUT status: status_$t { returned status } 
); EXTERN; 

%eject; 

{ Fill operations. } 



{ GPR_$REC:tangle fills a rectangle in the current bitmap. } 

PROCEDURE gpr_$rectangle ( 

IN rect: gpr_$window_t; { the rectangle to fill } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$TRAPEZOID fills a trapezoid in the current bitmap. } 

PROCEDURE gpr_$trapezoid ( 

IN trap: gpr_$trap_t; { the trapezoid to fill } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$MULTITRAPEZOID fills a list of trapezoids in the current bitmap. } 

PROCEDURE gpr_$multi trapezoid ( 

IN t_list: UNIV gpr_$trap_list_t; { the trapezoids to fill } 
IN n_traps: integer; { how many } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$TRIANGLE fills a triangle in the current bitmap. } 

PROCEDURE gpr_$triangle ( 

IN pi, p2, p3: gpr_$position_t; { vertices of the triangle } 
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OUT status: status_$t { returned status } 
) ; EXTERN; 



{ GPR_$START_PGON starts a polygon boundary loop. } 

PROCEDURE gpr_$start_pgon ( 

IN X, y: gpr_$coordinate_t; { the first point in the loop } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$PGON_POLYLINE defines a series of line segments as part of 
the current polygon boundary loop. } 

PROCEDURE gpr_$pgon_polyline ( 

IN X, y: UNIV gpr_$coordinate_array_t; { the list of 

endpoints } 
IN npoints: integer; { how many } 
OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$CI/DSE_FILL_PGasi closes and fills the currently open polygon. } 

PROCEDURE gpr_$close_fill_pgon ( 

OUT status: status_$t { returned status } 
); EXTERN; 



{ GPR_$CLOSE_RETORN_PGON closes the currently open polygon, 
decomposes it, and returns the list of trapezoids. } 

PROCEDURE gpr_$close_return_pgon ( 

IN list_size: integer; { how irany trapezoids t_list 

can hold } 
OUT t_list: UNIV gpr_$trap_list_t; { the trapezoid list } 
OUT n_traps: integer; { how many trapezoids in the 

whole decomposition } 
OUT status: status_$t { returned status } 
); EXTERN; 
%eject; 
{ Direct graphics calls. } 



{ GPR_$SETJ\CQ_TIME_OUT sets the acquire timeout for a display in 
direct mode. } 
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PROCEDURE gpr_$set_aoq_tiine_out ( 

IN time_out : time_$clock_t; { expected raaxtime that window 

will be in use } 
OUT sts : status_$t { returned status } 
); EXTERN; 



{ GPR_SET_OBSCURED_OPr sets obscured window behavior for acquiring a 
display in direct mode. } 

PROCEDURE gpr_$set_obscured_opt ( 

IN if_obscured: gpr_$obscured_opt_t; { one of four options } 
OUT sts: status_$t { returned status } 

); EXTERN; 



{ GPR_$ACQUIRE_DISPliAy gives the user exclusive access to all display 

operations in the acquired window, returning whether window was unobscured. } 

FUNCTION gpr_$acquire_display ( 

OUT sts: status_$t { returned status } 
) : boolean; EXTERN; 



{ GPR_$INQ_VIS_LIST returns list of visible subwindows when a window is 
obscured. } 

PROCEDURE gpr_$inq_vis_list ( 

IN slots_avail: integer; { number of subwin to return } 
OUT slots_total: integer; { number of subwin that exist } 
OUT vis_list: UNIV gpr_$window_list_t; { list of vis subwindows } 
OUT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$FORCE_RELEASE releases the display regardless of how many times it 
was previously acquired. } 

PROCEDURE gpr_$f orce_release ( 

OUT acq_rel_cnt: integer; { number of times window was 

acquired } 
OUT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$RELEASE_DI SPLAY decrements the display-acquired count. } 
PROCEDURE gpr_$release_display ( 
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CXJT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_REFRESHLENTRY provides two procedures which will refresh the 
window and refresh hidden display memory. } 

PROCEDURE gpr_$set_refresh_entry( 

IN rwin_proc: gpr_$rwin_pr_t; { entry point for refreshing 

window } 
IN rhdin^proc: gpr_$rhdin_pr_t; { entry point for hidden 

display memory } 
OUT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$SET_AUTO_REFRESH tells the display mangager whether to save 
window's contents and refresh screen when needed. } 

PROCEDURE gpr_$set_auto_refresh( 

IN auto_ref resh: boolean; { on or off } 
OUT sts: status_$t { returned status } 
); EXTERN; 

%eject; 

{ Input calls. } 



{ GPR_$EVENT_WAIT waits for input or timeout; returns boolean to indicate 
unobscured window. } 

FUNCTION gpr_$event_wait( 

OUT event_type: gpr_$event_t; { type of event that occurred } 

OUT event_data: char; { char associated with the event } 

OUT pos: gpr_$position_t; { x and y position } 

OUT sts: status_$t { returned status } 
) : boolean; EXTERN; 



{ GPR_$COND_EVENT_WAIT is like GPR_$EVINT_WAIT but returns immediately. } 

FUNCTION gpr_$cond_event_wait ( 

OUT event_type: gpr_$event_t; { type of event that occurred } 

OUT event_data: char; { char associated with the event } 

OUT pos: gpr_$position_t; { x and y position } 

OUT sts: status_$t { returned status } 
) : boolean; EXTERN; 
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{ GPR_$ENABLE_INPUT enables the given event type and set of keys to be 
recognized by event wait calls. } 

PROCEDURE gpr_$enable_input ( 

IN event_type: gpr_$event_t; { specified event type } 
IN key_set: gpr_$keyset_t; { set of char } 
OUT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$DISABLE_INPUT disables the given event type. } 

PROCEDURE gpr_$disable_input ( 

IN event_t^^: gpr_$everit_t; { specified event type to 

disable } 
OUT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$GET_EC gets the gpr input eventcount. } 



PROCEDURE gpr_$get_ec( 

IN gpr_key: gpr_$ec_key_t; 

OUT ec_ptr: ec2_$ptr_t; 
OUT sts: status_$t 
); EXTERN; 



{ specifies which eventcount 

to obtain } 
{ event count address } 
{ returned status } 



{ GPR_$SET_INPUT_SID establishes the stream id for gpr input in frame mode 
if not standard input, } 



PROCEDURE gpr_$set_input_sid ( 

IN sid: stream_$id_t; 
OUT sts: status_$t 
); EXTERN; 



{ stream id of input source } 
{ returned status } 



{ GPR_$SET_WINDOW_ID sets the character identifying the current displayed 
bitmap for input identification purposes. } 

PROCEDURE gpr_$set_window_id ( 

IN id_char: char; { character to identify window } 
OUT sts: status_$t { returned status } 
); EXTERN; 



{ GPR_$INQ_WINDOW_ID returns the character identifying the current displayed 
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bitmap for input identification purposes, } 

PROCEDURE gpr_$inq_windowL_id ( 

OUT id_char: char; { character to identify window } 
OUT sts: status_$t { returned status } 
); EXTERN; 

%eject; 

{ Imaging format calls. } 



{ GPR_$SET_IMAGING_FORMAT sets the DN600 display format. } 

PROCEDURE gpr_$set_imaging_format ( 

IN format: gpr_$imaging_format_t; { the imaging format } 
OUT status: status_$t { returned status } 

); EXTERN; 



{ GPR_$I1SQ_IMAGING_F0RMAT returns the current DN600 display format. } 

PROCEDURE gpr_$inq_imaging_format ( 

OUT format: gpr_$imaging_format_t; { the current imaging 

format } 
OUT status: status_$t { returned status } 

); EXTERN; 

%eject; 
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APPENDIX C 
INSERT FILE FOR C 



This appendix contains the insert file for C. TPhis file includes 
error messages, color values, data types, and data structures. For 
a listing of data types and data structures in a table format, see 
Chapter 9. 



define gpr_$operation_ok 0x00000000 
define gpr_$not_initialized 0x06010001 
define gpr_$already_initialized 0x06010002 
define gpr_$wrong_display_hardware 0x06010003 
define gpr_$illegal_for_frame 0x06010004 
define gpr_$must_borrow_display 0x06010005 
define gpr_$no_attributes_defined 0x06010006 
define gpr_$no_more_space 0x06010007 
define gpr_$dimension_too_big 0x06010008 
define gpr_$dimension_too_small 0x06010009 
define gpr_$bad_bitmap 0x0601000A 
define gpr_$bad_attribute_block 0x0601000B 
define gpr_$window_out_of_bounds 0x0601000C 
define gpr_$source_out_of_bounds 0x0601000D 
define gpr_$dest_out_of_bounds 0x0601000E 
define gpr_$invalid_plane 0x0601000F 
define gpr_$cant_deallocate 0x06010010 
define gpr_$coord_out_of_bounds 0x06010011 
define gpr_$invalid_color_map 0x06010012 
define gpr_$invalid_raster_op 0x06010013 
define gpr_$bitmap_is_read_only 0x06010014 
define gpr_$internal_error 0x06010015 
define gpr_$font_table_full 0x06010016 
define gpr_$bad_font_file 0x06010017 
define gpr_$invalid_font_id 0x06010018 
define gpr_$window_obscured 0x06010019 
define gpr_$not_in_direct_mode 0x0601001A 
define gpr_$not_in_polygon 0x0601001B 
define gpr_$kbd_not_aoq 0x0601001C 
define gpr_$display_not_acq 0x0601001D 



C-1 i^pendix C 



define gpr_ 

define gpr. 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 

define gpr_ 



.$illegal_pixel_values 0x0601001E 
.$illegal_when_imaging Ox 0601001F 
.$invalid_iniaging_fonnat 0x06010020 
.$must_release_display 0x06010021 
.$cant_mix_inodes 0x06010022 
.$no_input_enabled 0x06010023 
.$duplicate_points 0x06010024 
.$array_not_sorted 0x06010025 
.$character_not_in_font 0x06010026 
$illegal_fill_pattern 0x06010027 
.$illegal_f ill_scale 0x06010028 
.$incorrect_aligninent 0x06010029 
.$illegal_text_iHth 0x0601002A 
.$unable_to_rotate_font 0x0601002B 
.$font_is_read_only 0x0601002C 
.$illegal_pattern_length 16 0601002D 



.$black 
.$white OxFFFFFF 
.$red OxFFOOOO 
.$green OxOOFFOO 
.$blue OxOOOOFF 
.$cyan OxOOFFFF 



define gpr_$nagenta OxFFOOFF 
define gpr_$yellow OxFFFFOO 

define gpr_$transparent (-1) 

define gpr_$background (-2) 

define gpr_$string_size 256 
define gpr_$max_x_size 4096 
define gpr_$itax_y_size 4096 
define gpr_$highest_plane 7 
define gpr_$nil_attribute_desc 

define gpr_$nil_bitinap_desc 



define gpr_$max_biTif_group 
define gpr_$binf_inajor_version 1 
define gpr_$binf_ininor_version 1 



/* color 
/* color 
/* color 
/* color 
/* color 
/* color 
(blue 
/* color 
/* color 



value for black */ 

value for white */ 

value for red */ 

value for green */ 

value for blue */ 

value for cyan 

+ green) */ 

value for iiagenta (red + blue) 

value for yellow (red + green) 



V 
V 



/* pixel value for transparent 

(no change) */ 
/* pixel value for window background */ 



/* 
/* 
/* 
/* 
/* 

/* 



number of chars in a gpr string */ 
max bits in bitmap x dimension */ 
max bits in bitmap y dimension */ 
max plane number in a bitmap */ 
value of a descriptor of 
nonexistent attributes */ 
value of a descriptor of a 
nonexistent bitmap */ 



/* max group in external bitmaps */ 



typedef enum { gpr_$keystroke, gpr_$buttons, gpr_$locator, 

gpr_$entered_window, gpr_$left_window, 

gpr_$locator_stop, gpr_$no_event 
} gpr_$event_t; 

unsigned long gpr_$keyset_t[4] ; /* This is supposed to be SET OF char */ 



typedef enum { gpr_$ok_if_obs, gpr_$error_if_obs, 
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gpr_$pop_if_obs, gpr_$block_if_obs 
} gpr_$obscured_opt_t; 

typedef enum {gpr_$input_ec} gpr_$ec_key_t; 

typedef void (*gpr_$rwin__pr_t) () ; 
typedef void (*gpr_$rhdm_pr_t) () ; 

/* the five ways to use this package */ 
typedef enum { 

gpr_$borrow, 

gpr_$frame, 

gpr_$no_display , 

gpr_$direct, 

gpr_$bor r ow_nc 
} gpr_$display_itiode_t; 

/* possible display hardware cx)nf igurations */ 
typedef enum { 

gpr_$bw_800xl024, 

gpr_$bwL.1024x800 , 

gpr_$color_1024xl024x4 , 

gpr_$color_1024xl024x8, 

gpr_$RESE WEDx4 , 

gpr_$RESERVEDx8 
} gpr_$display_cx)nfig_t; 

/* imaging vs interactive display formats */ 
typedef enum { 

gpr_$interactive, 

gpr_$imaging_1024xl024x8 , 

gpr_$imaging_51 2x51 2x24 
} gpr_$imaging_format_t; 

/* bitmap coordinates */ 
typedef short gpr_$coordinate_t; 

/* lists of bitmap coordinates */ 
typedef gpr_$coordinate_t gpr_$coordinate_array_t[10] ; 

/* bitmap positions */ 
typedef struct { 

gpr_$coordinate_t x_coord, y_coord; 
} gpr_$position_t; 

/* bitmap offsets */ 
typedef struct { 

unsigned short x_size, y_size; 
} gpr_$offset_t; 

/* windows on a bitmap */ 
typedef struct { 

gpr_$position_t window_base; 
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gpr_$offset_t window_size; 
} gpr_$window_t; 

typedef gpr_$windov7_t gpr_$window_list_t[10] ; 

/* horizontal line segments */ 
typedef struct { 

gpr_$coordinate_t x_coord_l, x_coord_r, y_coord; 
} gpr_$horiz_seg_t; 

/* trapezoids with horizontal bases: defined as 2 horizontal 
line segments, top and bottom */ 
typedef struct { 

gpr_$horiz_segLt top, bot; 
} gpr_$trap_t; 

/* lists of trapezoids with horizontal bases */ 
typedef gpr_$trap_t gpr_$trap_list_t [10] ; 

/* graphics primitive strings */ 
typedef char gpr_$string_t [gpr_$string_size] ; 

/* bitmap plane numbers */ 
typedef unsigned short gpr_$plane_t; 

/* bitmap plane masks (bit vector) */ 
typedef short gpr_$raask_t; 

/* color values */ 
typedef linteger gpr_$color_t; 

/* pixel values */ 
typedef linteger gpr_$pixel_value_t; 

/* arrays of color values */ 
typedef gpr_$color_t gpr_$color_vector_t[256] ; 

/* arrays of pixel values */ 
typedef gpr_$pixel_value_t gpr_$pixel_array_t [131073] ; 

/* raster operation opcodes */ 
typedef unsigned short gpr_$raster_op_t; 

/* arrays of raster operation opcodes */ 
typedef gpr_$raster_op_t gpr_$raster_op_array_t[8] ; 

/* scalar type for directions */ 
typedef enum {gpr_$up, gpr_$down, gpr_$left, gpr_$right} gpr_$direction_t; 

/* line drawing styles */ 
typedef enum {gpr_$solid, gpr_$dotted} gpr_$linestyle_t; 

typedef short gpr_$line_pattern_t [4] ; 
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/* attribute block descriptors */ 
typedef linteger gpr_$attribute_desc_t; 

/* bitmap descriptors */ 
typedef linteger gpr_$bitinap_desc_t; 

typedef struct { 

unsigned short major, minor; 
} gpr_$version_t; 



typedef struct { 

unsigned short n_sects; 

unsigned short pixel_size; 

unsigned short allocated_size; 

unsigned short bytes_per_line; 

linteger bytes_per_sect; 

integer *storage_offset; 
} gpr_$l:xnf_group_header_t? 

typedef gpr_$bmf_group_header_t gpr_$lOTf_group_header_array_t 
[gpr_$max_bmf_group+l] ; 

typedef enum {gpr_$create,gpr_$update, gpr_$write, gpr_$readonly} 
gpr_$access_mode_t ; 

eject 
/* Initialization and termination. */ 



/* GPR_$INIT initializes the graphics primitive package. */ 
std_$call void gpr_$init () ; 

/* GPR_$TERMINA.TE terminates this package's operation. */ 

std_$call void gpr_$terminate () ; 
eject 
/* Set and inquire operations for the display. */ 

/* GPR_$INQ_OONFIG returns the current display configuration. */ 
std_$call void gpr_$inq_conf ig () ; 

/* GPR_$SET_CDLOR_MAP gives new values for the color map. */ 
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std_$call void gpr_$set_color_iTap () ; 

/* GPR_$INQ_GOIjOIL.MAP returns current values in the color map. */ 
std_$call void gpr_$inq_color_iiap ( ) ; 

/* GPR_$SET_CURSOR_PATTERN loads a cursor pattern. */ 
std_$call void gpr_$set_cursor_pattem () ; 



/* GPR_$SET_ajRSOR_ACTIVE specifies whether the cursor should be 
on or off. V 

std_$call void gpr_$set_cursor_active () ; 



/* GPR_$SET_ajRSOIL.POSITION gives the position at which the cursor is 
to be displayed, in the current bitmap. */ 

std_$call void gpr_$set_cursor_position () ; 

/* GPR_$SET_ORIGIN gives the cursor- relative psoition of its pixel 
which is to be placed at the cursor position. */ 

std_$call void gpr_$set_cursor_origin () ; 

/* GPR_$INQ_ajRSOR returns information about the cursor. */ 
std_$call void gpr_$inq_cursor () ; 



/* GPR_$WAIT_PRAME causes the color display hardware to defer processing 
further requests until the next end-of -frame. */ 

std_$call void gpr_$wait_frame () ; 
eject 
/* Bitmap control functions. */ 



/* GPR_$SET_BI'IMAP establishes the current bitmap for subsequent 
operations. */ 
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std_$call void gpr_$set_bitmap () ; 

/* GPR_$INQ_BiaMAP returns a descriptor of the current bitmap. */ 
std_$call void gpr_$inq_bitinap ( ) ; 

/* GPR_$ALLOCATE_BITMAP allocates a bitmap in main memory. */ 
std_$call void gpr_$allocate_bitmap () ; 



/* GPR_$ALLOCATE_BI'IMAP_NC allocates a bitmap in main memory without 
zeroing it. */ 

std_$call void gpr_$allocate_bitmap_nc (); 



/* GPR_$ALLOCATE_HnyLBITiyiAP allocates a bitmap in hidden_display memory. */ 
std_$call void gpr_$allocate_hdm_bitmap () ; 

/* GPR_$OPEN_BlTMAP_FILE obtains access to an external bitmap */ 
std_$call void gpr_$open_bitmap_f ile () ; 

/* GPR_$DEALLOCATE_BITiyiAP deallocates a bitmap allocated by ALLOCATE_BI'IMAP. */ 
std_$call void gpr_$deallocate_bitmap () ; 



/* GPR_$INQ_BITMAP_POINTER returns a pointer to the storage/display memory 
for the given bitmap and the number of words each scan line occupies. 
This information can be used to directly manipulate the bits in the bitmap. */ 

std_$call void gpr_$inq_bitmap_pointer () ; 



/* GPR_$INQ_BM_BIT_OFFSET returns the number of bits in the most significant 
part of the first word of each scanline which are not part of the given 
bitmap. In other words, the offset is the number of bits between a 16-bit 
word boundary and the left edge of the bitmap. 
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Currently, this number can only be nonzero for direct graphics bitmaps. */ 
std_$call void gpr_$inq_bm_bit_off set () ; 



/* GPR_$SELECT_CDLOR_FRAME selects whether frame (top 1024 lines) or 

frame 1 (bottom 1024 lines) is visible. Normally frame is visible. */ 



std_$call void gpr_$select_color_f rame () ; 



/* GPR_$REMAP_CDLOR_MEMORY sets the plane of frame of color display memory 
(normally visible) which is mapped at the address returned by 
inq_bi™ap_pointer. V 

std_$call void gpr_$rQnap_color_memory ( ) ; 



/* GPR_$REMAP_(X)IiOR_MEM0RY_l sets the plane of frame 1 of color display 
memory (normally hidden) which is mapped at the address returned by 
INQ_BI'EMAP_POINTER. */ 

std_$call void gpr_$rQnap_color_memory_l () ; 

/* GPR_$CDLOR_Z00iyi sets the zoom scale factors for the color display. */ 
std_$call void gpr_$color_zoom () ; 



/* GPR_$ENABLE_DIRECT_ACCESS waits for display hardware to finish current 
operations so that the user can access display memory directly. */ 

std_$call void gpr_$enable_direct_access (); 



/* GPR_$SET_BnMAP_DIiyENSIONS changes the size and number of planes 
of the given bitmap. */ 

std_$call void gpr_$set_bitmap_dimensions () ; 



/* GPR_$INQ_BITMAP_DIMEasiSIONS returns the size and number of planes 
of the given bitmap. */ 

std_$call void gpr_$inq_bitmap_dimensions () ; 
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/* GPR_$AIli(XATE_ATTRIBUTE_BLOCK allocates an attribute block, 
initialized to default settings. */ 

std_$call void gpr_$allocate_attribute_block () ; 



/* GPR_$DEAIJX)a^TE_ArTRIBUTE_BL(XK deallocates an attribute block allocated 
by ALIiOCATE_AITRIBUTE_B[iOCK. */ 

std_$call void gpr_$deallocate_attribute_block () ; 



/* GPR_$SET_ATTRIBU'IE_BLOCK establishes the given attributes as the 
attributes of the current bitmap. */ 

std_$call.void gpr_$set_attribute_block {) ; 



/* GPR_$ATTRIBUTE_BLOCK returns as the function value a descriptor of 
the attributes of the given bitmap. */ 

std_$call gpr_$attribute_desc_t gpr_$attribute_block () ; 
eject 
/* Set and inquire operations for bitmap attributes. */ 



/* GPR_$SET_attribute sets an attribute in the current bitmap. 
The list of calls follows. */ 

std_$call void gpr_$set_clip_window ( ) ; 

std_$call void gpr_$set_clipping_active () ; 

std_$call void gpr_$set_text_font () ; 

std_$call void gpr_$set_text_path () ; 

std_$call void gpr_$set_coordinate_origin () ; 

std_$call void gpr_$set_plane_mask () 

std_$call void gpr_$set_draw_value () 

std_$call void gpr_$set_text_value () 

std_$call void gpr_$set_text_background_value () ; 
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std_$call void gpr_$set_fill_value (); 

std_$call void gpr_$set_fill_background_value () ; 

std_$call void gpr_$set_f ill_pattern () ; 

std_$call void gpr_$set_raster_op () ; 

std_$call void gpr_$set_linestyle () ; 

std_$call void gpr_$set_line_pattern () ; 

std_$call void gpr_$set_character_width {) ; 

std_$call void gpr_$set_horizontal_spacing () ; 

std_$call void gpr_$set_space_size () ; 

/* GPR_$INQ_attributes returns the current settings of a group 

of attributes for the current bitmap. */ 

std_$call void gpr_$inc[_constraints (); 

std_$call void gpr_$inq_text (); 

std_$call void gpr_$inq_text_path () ; 

std_$call void gpr_$inq_ooordinate_origin () ; 

std_$call void gpr_$inq_draw_value () ; 

std_$call void gpr_$inq_text_values () ; 

std_$call void gpr_$incL.f ill_value () ; 

std_$call void gpr_$inq_fill_background_value () ; 

std_$call void gpr_$inq_fill_pattern (); 

std_$call void gpr_$inq_raster_ops () ; 

std_$call void gpr_$inq_linestyle () ; 

std_$call void gpr_$inq_line_pattern () ; 

std_$call void gpr_$inq_character_width () ; 

std_$call void gpr_$inq_horizontal_spacing () ; 

std_$call void gpr_$inq_space_size () ; 
eject 
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/* Drawing operations. */ 

/* GPR_$MOVE sets the CP to the given position. */ 
std_$call void gpr_$inove () ; 

/* GPR_$INQ_CP returns the current position. */ 
stcl_$call void gpr_$inq_cp () ; 



/* GPR_$Lnffi; draws a line from the CP to the given position 
and sets the CP to the given position. */ 

std_$call void gpr_$line () ; 



/* GPR_$POLYLINE does a series of LINEs, starting from the CP. */ 
std_$call void gpr_$polyline () ; 

/* GPR_$MULTILIME does a series of alternate MOVEs and LINEs. */ 
std_$call void gpr_$multiline () ; 

/* GPR_$DRftW_BOX draws a rectangular box */ 
std_$call void gpr_$draw_box () ; 



/* GPR_$ARC_3P draws an arc from current point through two points 
p2 and p3. */ 

std_$call void gpr_$arc_3p ( ) ; 



/* GPR_$CIRCLE draws a circle of radius around point center. */ 
std_$call void gpr_$circle () ; 
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/* GPR_$CIRCLE_FILLED draws a filled circle of radius around point center. */ 
std_$call void gpr_$circle_filled (); 



/* GPR_$SPLINE_CUBIC_P draws a parametric cubic spline through the 
control points. */ 

std_$call void gpr_$spline_cubic_p (); 



/* GPR_$SPLINE_CUBIC_X draws a cubic spline as a function of x through 
the control points. */ 

std_$call void gpr_$spline_cubic_x () ; 



/* GPR_$SPLINE_aBIC_Y draws a cubic spline as a function of y through 
the control points. */ 

std_$call void gpr_$spline_cubic_y ( ) ; 
eject 
/* Text operations. */ 



/* GPR_$LOAD_FONT_FILE loads a font contained in a file into an appro- 
priate area (based on the current display mode and configuration) . */ 

std_$call void gpr_$load_font_f ile () ; 



/* GPR_$UNLOAD_FONT_FILE unloads a font that has been loaded by 
LQAD_PONT_FILE. */ 

std_$call void gpr_$unload_font_file () ; 



/* GPR_$TEXT writes text to a bitmap from the current position ("CP"). */ 
std_$call void gpr_$text () ; 

/* GPR_$INQ_TEXT_EXTENT returns the x- and y-off sets the given string 
would span if written with TEXT. */ 
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std_$call void gpr_$inq_text_extent {) ; 



/* GPR_$INQ_TEXT_OFFSET returns the x- and y-off sets that must be added to the 

coordinates of the desired upper left pixel of the string to give the pixel 

from which the TEXT call should be made, and the x_offset of the pixel 
which would be the updated CP. */ 

std_$call void gpr_$inq_text_of f set () ; 



/* GPR_$REPLICATE_FONT creates and loads a rea^write copy of the 
original font. */ 

std_$call void gpr_$replicate_font () ; 
eject 
/* Data transfer operations. */ 



/* GPR_$CLEAR clears the current bitmap to a given pixel value. */ 
std_$call void gpr_$clear () ; 



/* GPR_$READ_PIXELS reads the pixels from the given window of the current 
bitmap and stores them in a pixel array. */ 

std_$call void gpr_$read_jpixels () ; 



/* GPR_^'7RITE_PIXELS writes the pixels from a pixel array into the given 
window of the current bitmap. */ 

std_$call void gpr_$write_pixels (); 
eject 
/* BLT operations. */ 



/* GPR_$PIXEL_BLT moves a rectangle of whole pixels from the source 
bitmap to a position in the current bitmap. */ 

std_$call void gpr_$pixel_blt () ; 

/* GPR_$BIT_BLT moves a rectangle of bits from a plane of the source 
bitmap to a position in a plane of the current bitmap. */ 
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std_$call void gpr_$bit_blt () ; 

/* GPIL.$ADDITIVE_BLT moves a rectangle of bits from a plane of the source 
bitmap to a position in every plane of the current bitmap. */ 

std_$call void gpr_$additive_blt () ; 
eject 
/* Fill operations. */ 



/* GPR_$RECTANGLE fills a rectangle in the current bitmap. */ 
std_$call void gpr_$rectangle () ; 

/* GPR_$TE?APEZOID fills a trapezoid in the current bitmap. */ 
std_$call void gpr_$trapezoid () ; 

/* GPR_$MULTITRAPEZOID fills a list of trapezoids in the current bitmap. */ 
std_$call void gpr_$multi trapezoid () ; 

/* GPR_$TRIANGLE fills a triangle in the current bitmap. */ 
std_$call void gpr_$triangle () ; 

/* GPR_$START_PGON starts a polygon boundary loop. */ 
std_$call void gpr_$start_pgon () ; 



/* GPR_$PGaSLPOLYLINE defines a series of line segments as part of 
the current polygon boundary loop. */ 

std_$call void gpr_$pgon_polyline () ; 



/* GPR_$CL0SE_FILE4_PGCN closes and fills the currently open polygon. */ 
std_$call void gpr_$close_fill_pgon (); 
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/* GPR_$CLOSE_RETOR]SLPGaa closes the currently open polygon, 
decomposes it, and returns the list of trapezoids. */ 

std_$call void gpr_$close_return_pgon () ; 
eject 

/* direct graphics */ 

std_$call void gpr_$set_aoq_tiine_out() ; 

/* GPR_SET_OBSaJRED_OPT sets obscured selection attribute for display in 
direct mode */ 

std_$call void gpr_$set_obscured_opt() ; 

/* GPR_$ACQUIRE_DISPLAy gives the user exclusive access to all display 
operations 
in the acquired window */ 

std_$call boolean gpr_$acquire_display() ; 

/* GPR_$INQ_VIS_LIST returns list of visible subwindows when a window is 
obscured */ 

std_$call void gpr_$inq_vis_list() ; 

/* GPR_$FORCE_RELEASE releases the display regardless of how many times it 
was previously acquired */ 

std_$call void gpr_$force_release() ; 

/* GPR_$RELEASE_DISPriAY will release the display only if acq_rel_cnt is 1 */ 
std_$call void gpr_$release_display ( ) ; 

/* GPR_$SET_REFRESH_ENTRY provides two std_$call voids which will refresh 
the user's window and refresh hidden display memory */ 

std_$call void gpr_$set_refresh_entry() ; 

/* GPR_$SET_A[JTO_REFRESH tells DM to save bitmap and refresh screen 
when needed */ 
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std_$call void gpr_$set_auto_refresh() ; 

/* GPR_$EVENT_WAIT hangs until input or time out; returns boolean to indicate 
obscured window */ 

std_$call boolean gpr_$event_wait() ; 

/* GPR_$COND_EVENT_WAIT returns immediately and reports if any input */ 
std_$call boolean gpr_$cond_event_wait { ) ; 

V 

/* GPR_$ENABLE_INPUT enables event type and selected set of keys to be 
recognized by event_wait */ 

std_$call void gpr_$enable_input() ; 

/* GPR_$DISABLE_INP[JT disables event type */ 
std_$call void gpr_$disable_input ( ) ; 

/* GPR_$GET_EC gets event count */ 

std_$call void gpr_$get_ec() ; 

/* GPR_$SET_INPUT_SID establishes the stream id for gpr input in frame mode 
if not standard input */ 

std_$call void gpr_$set_input_sid() ; 

/* GPR_$SET_WINDOW_ID sets the character identifying the current displayed 
bitmap for input identification purposes */ 

std_$call void gpr_$set_window_id() ; 

/* GPR_$INQ_WINDOW_ID returns the character identifying the current displayed 
bitmap for input identification purposes */ 

std_$call void gpr_$inq_window_id ( ) ; 
eject 
/* Imaging format calls */ 

/* GPR_$SET_IiyiAGING_PORMAT sets the DN600 display format */ 

std_$call void gpr_$set_imaging_format() ; 

/* GPR_$INQ_IiyiAGINS_PORMAT returns the current DN600 display format */ 
std_$call void gpr_$inq_imaging_format() ; 
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APPENDIX D 
INSERT FILE FOR FORTRAN 



This appendix contains the insert file for FORTRAN. 



•Status code definitions: 



integer*4 



+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 

+ 
+ 
+ 
+ 
+ 
+ 
+ 



gpr_$operation_ok, gpr 

gpr_$already_initialized, gpr 

gpr_$illegal_for_frame, gpr 

gpr_$no_attributes_defined, gpr 



gpr_$dimension_too_big , 
gpr_$bad_bitinap, 
gpr_$window_out_of_bounds , 
gpr_$dest_out_of_bounds , 
gpr_$cant_deallocate , 
gpr_$inval id_color_map, 
gpr_$bitniap_is_read_only , 
gpr_$f ont_table_f ull , 
gpr_$invalid_font_id, 
gpr_$not_in_di rect_inode , 
gpr_$idDd_not_acq , 
gpr_$illegal_pixel_values , 



gpr 
gpr 
gpr 
gpr 
gpr. 
gpr 
gpr. 
gpr 
gpr 
gpr 
gpr 
gpr_ 
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gpr_$invalid_iinaging_f ormat, gpr_ 

gpr_$cant_inix_iiiodes, gpr_ 

gpr_$duplicate_points, gpr_ 

gpr_$character_not_in_font, gpr_ 

gpr_$illegal_fill_scale, gpr_ 

gpr_$illegal_text_path, gpr_ 

gpr_$font_is_read_only, gpr_ 



.$not_ini tial ized , 
.$wrong_display_harc^are , 
.$must_bor row_display , 
.$no_inor e_space , 
.$dimension_too_small , 
.$bad_attribute_block, 
.$source_out_of_bounds , 
.$inval id_plane , 
.$coord_out_of_bounds , 
.$inval id_raster_op, 
.$internal_er ror , 
.$bad_font_file, 
.$windowL_obscur ed , 
.$not_in_polygon, 
.$display_not_aa3 , 
.$illegal_when_iitaging 

.$must_release_display , 
.$no_input_enabled , 
.$array_not_sorted, 
.$illegal_fill_pattern, 
.$incorrect_alignment, 
.$unable_to_rotate_f ont , 
.$il legal_pattern_length 



parameter ( 

+ gpr_$operation_ok 
+ gpr_$not_initialized 
+ gpr_$already_initialized 
+ gpr_$wrong_display_hardware 



16 00000000, 
16 06010001, 
16 06010002, 
16 06010003, 
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+ gpr_$illegal_for_frame 
+ gpr_$must_borrow_display 
+ gpr_$no_attributes_defined 
+ gpr_$no_more_space 
+ gpr_$diinension_too_big 
+ gpr_$diinension_too_small 
+ gpr_$bad_bitraap 
+ gpr_$bad_attribute_block 
+ gpr_$window_out_of_bounds 
+ gpr_$source_out_of_bounds 
+ gpr_$dest_out_of_bounds 
+ gpr_$invalid_plane 
parameter ( 
+ gpr_$cant_deallocate 

gpr_$coord_out_of_bounds 
gpr_$inval id_cx>lor_map 
gpr_$inval id_raster_op 
gpr_$bitiiap_is_read_only 
gpr_$internal_error 
gpr_$font_table_full 
gpr_$bad_f ont_f il e 
gpr_$inval id_f ont_id 
gpr_$window_obscured 
gpr_$not_in_di rectjnode 
gpr_$not_in_polygon 
gpr_$kbd_not_acq 
gpr_$display_not_acq 
gpr_$illegal_pixel_values 
gpr_$illegal_when_iiiaging 
parameter ( 

+ gpr_$invalid_iitaging_fonnat 
gpr_$must_release_display 
gpr_$cant_iiiix_nK)des 
gpr_$no_input_enabled 
gpr_$duplicate_points 
gpr_$array_not_sorted 
gpr_$characte r_not_in_f ont 
gpr_$illegal_f il l_pattern 
gpr_$illegal_fill_scale 
gpr_$incor rect_alignment 
gpr_$illegal_text_^th 
gpr_$unabl e_to_rotate_f ont 
gpr_$font_is_read_only 
gpr_$illegal_pattem_length 



16 06010004, 
16 06010005, 
16 06010006, 
16 06010007, 
16 06010008, 
16 06010009, 
16 0601000A, 
16 0601000B, 
16 0601000C, 
16 0601000D, 
16 0601000E, 
16 0601000F) 

16 06010010, 
16 06010011, 
16 06010012, 
16 06010013, 
16 06010014, 
16 06010015, 
16 06010016, 
16 06010017, 
16 06010018, 
16 06010019, 
16 0601001A, 
16 0601001B, 
16 0601001C, 
16 0601001D, 
16 0601001E, 
16 0601001F) 

16 06010020, 
16 06010021, 
16 06010022, 
16 06010023, 
16 06010024, 
16 06010025, 
16 06010026, 
16 06010027, 
16 06010028, 
16 06010029, 
16 0601002A, 
16 0601002B, 
16 0601002C, 
16 0601002D) 



"Other constant definitions: 

integer*2 
+ gpr_$string_size, 
+ gpr_$max_x_size, gpr_$max_X-Size, 
+ gpr_$highest_plane, 
+ gpr_$max_binf_group. 
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+ gpr_$binf_inajor_version, 

+ gpr_$tanf_ininor_version 

integer*4 

+ gpr_$black, gpr_$white, 

+ gpr_$red, gpr_$green, gpr_$blue, 

+ gpr_$cyan, gpr_$magenta, gpr_$yellow, 

+ gpr_$transparent, gpr_$background, 

+ gpr_$nil_attribute_desc, gpr_$nil_bitinap_desc 

parameter ( 

+ gpr_$string_size = 256, 

+ gpr_$itax_x_size = 4096, gpr_$raax_7_size = 4096, 

+ gpr_$highest_plane = 7, 

+ gpr_$nax_binf_group = 0, 

+ gpr_$binf_inajor_version = 1, 

+ gpr_$l:Miif_ininor_version = 1) 

parameter ( 

+ gpr_$black = 0, gpr_$white = 16 FFFFFF, 

+ gpr_$red = 16 FFOOOO, 

+ gpr_$gree]i = 16 OOFFOO, 

+ gpr_$blue = 16 OOOOFF, 

+ gpr_$CYan = 16 OOFFFF, 

+ gpr_$magenta = 16 FFOOFF, 

+ gpr_$yellcfw = 16 FFFFOO, 

+ gpr_$transparent = -1, gpr_$background = -2, 

+ gpr_$nil_attribute_desc = 0, gpr_$nil_bitmap_desc = 0) 

C — the five ways to use this package 

integer*2 
+ gpr_$borrow, gpr_$frame, gpr_$no_display, gpr_$direct, 
+ gpr_$borrow_nc 

!ter ( 

gpr_$borrow = 0, gpr_$frame = 1, gpr_$no_display = 2, 

gpr_$direct = 3, gpr_$borrow_nc = 4) 



parameter ( 
+ 

+ 



C — possible display har^are configurations 

integer*2 
+ gpr_$bw_800xl024, gpr_$bw_1024x800 , 
+ gpr_$color_1024xl024x4, gpr_$color_1024xl024x8, 
+ gpr_$RESERVEDx4, gpr_$RESERVEDx8 

parameter ( 
+ gpr_$bw_800xl024 = 0, gpr_$bw_1024x800 = 1, 
+ gpr_$oolor_1024xl024x4 = 2, gpr_$color_1024xl024x8 = 3, 
+ gpr_$RESER7EDx4 = 4, gpr_$RESERVEDx8 = 5) 

C — imaging vs interactive display formats 
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integer*2 
+ gpr_$interactive, 

+ gpr_$imging_1024xl024x8, 

+ gpr_$iinaging_51 2x51 2x24 

parameter ( 

+ gpr_$interactive = 0, 
+ gpr_$iinaging_1024xl024x8 = 1, 
+ gpr_$iinagingL512x512x24 = 2) 

C directions 

integer*2 
+ gpr_$upr gpr_$down, gpr_$left, gpr_$right 

parameter ( 
+ gpr_$up = 0, gpr_$down = 1, gpr_$left = 2, gpr_$right = 3) 

C line styles 

integer*2 
+ gpr_$solid, gpr_$dotted 

parameter ( 
+ gpr_$solid = 0, gpr_$dotted = 1) 

C — event types 

integer*2 
+ gpr_$keystroke, gpr_$buttons, gpr_$locator, 
+ gpr_$entered_window, gpr_$left_window, gpr_$locator_stop, 
+ gpr_$no_e7ent 

parameter ( 
+ gpr_$keystroke = 0, gpr_$buttons == 1, gpr_$locator = 2, 
+ gpr_$entered_window = 3, gpr_$left_window = 4, 
+ gpr_$locator_stop = 5, gpr_$no_event = 6) 

C — obscured options for direct graphics 

integer*2 
+ gpr_$ok_if_obs, gpr_$error_if_obs, gpr_$pop_if_obs, 
+ gpr_$block_if_obs 

parameter ( 

+ gpr_$ok_if_obs = 0, gpr_$error_if_obs = 1, 
+ gpr_$pop_if_obs = 2, gpr_$block_if_obs = 3) 

integer*2 gpr_$create,gpr_$update, gpr_$write, gpr_$readonly 



i^pendix D D-4 



parameter ( 
+ gpr_$create = 0, gpr_$update = 1, 
+ gpr_$write = 2, gpr_$ readonly = 3) 



C — function declarations: 

integer*4 
+ gpr_$attribute_block 

logical 
+ gpr_$aGquire_display 

logical 
+ gpr_$event_wait 

logical 
+ gpr_$cond_event_wait 
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Attribute 

Specification of the manner in which a primitive graphic operation is to 
be performed (for example line type or text value) . Each bitmap has a 
set of attributes. 



Bitmap 

A three-dimensional array of bits having width, height, and depth. When 
a v^itmap is displayed, it is treated as a two-dimensional arr^ of sets 
of bits. The color of each displayed pixel is determined by using the 
set of bits in the corresponding pixel of the frame-buffer bitmap as an 
index into the color table. 



Bit plane 

A one-bit-deep layer of a bitmap. On a monochronatic display, displayed 
bitmaps contain one plane. On a color display, displayed bitmaps may 
contain more planes, depending on the hardware configuration and the 
number of bits per pixel. 

Borrow display mode 

A mode for use of the EOMAIN display whereby a program borrows the 
entire screen fran the Display Manager and performs graphics operations 
ty directly calling the display driver. 

Button 

A logical input device used to provide a choice from a small set of 
alternatives. Two physical devices of this type are function keys on a 
keyboard and selection buttons on a mouse. 

Qipping window 

A rectangular section of a bitmap outside of which graphics operations 
do not modify pixels. 
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Color map 

See Color table. 

Color table 

A set of color table entries, each of which can store one color value. 
Each color value contains red, blue, and green components. Each entry 
is accessed by a color table index. 

Color table entry 

One location in a color table. Each entry stores one color value which 
can be accessed fcy a corresponding color table index. 

Color table index 

An index to a particular color table entry. 

Color value 

The numeric encoding of a visible color. A color value is stored in a 
color table entry. Each color value is divided into three fields: the 
first stores the value of the red component of the color, the second 
stores the value of the green ccmponent of the color, and the third 
stores the value of the blue component. Each canponent value is 
specified as an integer in the range zero to 255, where zero is the 
absence of the primary color and 255 is the full intensity color. 

Core graphics system 

A package of grajiiics functional capabilities designed for building 
higher-level interactive computer graphics applications programs. 
Unlike grajiiics primitives, the Core graj^ics syston allows temporary 
storage of picture data during execution, with limited segmentation of 
the pictures. In addition, the Core ^stem uses device- independent 
coordinates. 

Current bitmap 

The bitmap on whicdi a program is currently operating. 

Current position 

In graj^ics primitives, the starting point of any line drawing and text 
operations. The current position is initially set at the coordinate 
position at the top left corner of the bitmap (0,0) . 

Direct mode 

A mode for use of the DOMAIN display whereby the program performs 
graj^ics operations in a window borrowed from the Display Manager. 
Direct mode allows graphics programs to coexist with other activities on 
the screen, with less Display Manager overhead than frame mode. 
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Event 

An input primitive which is associated with an interrupt from a device 
such as a keyboard, button, mouse, or touchpad. 

Font 

One set of aljiianumeric and special characters. The font in which text 
is to be displayed may be specified as an attribute. 

Frame 

A tv/o-dimensional data structure that holds a picture in a Display 
Manager pad. This structure is looked at through a Display Manager 
window. The structure can be larger (or smaller) than the window, and 
it can be scrolled. 



Frame buffer 

The digital memory in a raster display unit used to store a bitmap. 

Frame mode 

A mode for use of the DOMAIN display whereby a program performs graphics 
operations on a Display Manager pad. In this mode, the user has access 
to other processes through windows on the display, and can scroll the 
frame under the Display Manager window. In this mode, unlike direct 
mode, the Displ^ Manager will refresh the window when appropriate. 

Imaging display format 

An 8-bit or 24--bit color display format which allows display of an 
extended color range, but supports only limited graphics primitives 
operations. In an 8-bit imaging format, 8 bits are used to assign a 
pixel value (color map index) to each pixel. In a 24-bit imaging 
format, 24 bits are used to assign a pixel value to each pixel. An 
8-bit innaging format allows 256 colors to appear on the screen at one 
time. A 24-bit imaging format extends the possible color range to 16 
million different colors, with 512 x 512 pixels visible at one time. 

Initial bitmap 

The first bitmap created in a graphics session. 

Input device 

A device such as a function key, touchpad, or mouse that enables a user 
to provide input to a program. 

Input device number 

The identifier of one input device in an input device class. 
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Interactive display format 

A 4-bit or 8-bit color c3isplay format which supports all graphics 
primitives operations. In a 4-bit interactive format, 4 bits are used 
to assign a pixel value (color map index) to each pixel. In an 8-bit 
format, 8 bits are used to assign a pixel value to each pixel. A 4-bit 
format allows sixteen different colors to appear on the screen at one 
time. An 8-bit format allows 256 colors to appear on the screen at one 
time. 



Keyboard 

A logical input device used to provide character or text string input. 
One physical device of this type is the alphanumeric keyboard. 

Line st^le 

An attribute that specifies the style of lines and polylines (for 
example, solid or dotted) . 

Locator 

A logical input device used to specify one position in coordinate space 
(for example, a touchpad, data tablet, or mouse) . 

Logical input device 

An abstraction of an input device that provides a particular type of 
input data. This abstraction corresponds to a group of physical input 
devices which provide this type of input data.' 

No^-displa^ mode 

A mode for use of the DOMAIN system wherefcy a program creates a bitmap 
in nondisplayed memory and performs graphic operations there, 
bypassing the display. 

Picture element 

A single element of a two-dimensional displayed image or of a 
two-dimensional location within a bitmap. It is canmonly called a 
pixel . 

Pixel 

See Picture Elonent. 



Pixel value 

The set of bits at a two-dimensional location within a bitmap. A pixel 
value is used as an index to the color map. 
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Plane 

See Bit plane. 



Primitive 

The least divisible graphic operation which changes a bitanap (for 
example, lines, polylines, and text) . 



Primitive attribute 
See Attribute. 



R3B color model 

A model used to specify color values. It defines red, green, and blue 
as primary colors. All other colors are combinations of the primaries, 
including the three secondary colors (cyan, magenta, and yellcw) . 

Scan line 

A row of pixels; one horizontal line of a bitmap. 

Window 

A rectangular area of the visible screen. Parts of the area may be 
obscured ty other windows. 
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Acxjuiring the display, 8-1, 11-11 

Arc, 11-18 

Attribute block (see Bitmap) 

Attributes, 

changing, 3-11, 11-101 
clipping window, 3-8, 

11-88 
coordinate origin, 3-9 

11-111 
defaults for, 3-12 
draw value, 3-9, 11-117 
establishing, 3-11, 11-101 
fill background, 11-59, 11-118 
fill pattern, 11-60, 11-119 
line pattern, 11-64, 11-124 
line style, 3-9, 11-125 
plane mask, 3-9, 11-127 
raster operation, 3-9, 11-66, 

11-128 
text background 

value, 3-9, 11-133 
text font, 3-9, 11-134 
text value, 3-9, 11-136 



B 



Bit block transfer (see BLT) 
Bitmap, 3-1 

accessing bits in, 3-5 
allocating, 3-5, 11-15, 
allocating without clearing, 

11-16 
attribute block, 3-7 
allocating, 3-7, 11-14 
deallocating, 11-30 
descriptor, 3-11, 
11-19 
attributes (see also 

Attributes) 
cancelling, 3-4, 11-31 
creating, 3-4, 
current, 3-1, 3-3, 3-7 
descriptor, 3-6, 11-15, 11-16 
destination, 6-3 
dimensions, 3-1, 11-46, 11-104 
display memory in, 3-3 
depth, 3-1 



example, 10-3 

external storage, 3-4, 11-84 

identifying, 3-4, 11-46 

height, 3-1 

initial, 3-3, 3-4 

main memory, 3-3 

multiple plane, 3-5 

multiple-displayed, 3-7, 11-137 

not clearing, 11-43 

origin, 3-2 

plane, 3-1 

pointer to a, 3-6, 11-47 

size, 3-3, 11-104 

source, 3-6, 6-3 

width, 3-1 

window, 6-1, 6-5 

window origin, 6-3, 6-5 
Bit plane, 3-1 (see also 

Plane) 
Block transfer (see BLT) 
BLT, 6-1, 11-20 

additive, 6-1 

bit, 6-1 

for display driver, 6-2 

for GPR, 6-2 

pixel, 6-1 

plane mask with, 6-2, 11-127 

source and destination, 
6-3, 6-5 
Bor row-display mode (see Mode) 
Button, 7-3 (see also 
Event) 



Character 
width, 11-50, 11-106 
spacing, 11-67, 11-132 
set in FORTRAN, 11-36 

Clipping window, 6-5 
(see also Attributes) 

Color display, 2-2 
establishing, 4-2 
formats, 2-8, 4-3 

Color map, 4-1 (see 

also Color table) 

establishing, 4-2, 11-110 

4- and 8-bit formats, 4-3 

24-bit format, 4-4, 11-63, 

11-122 
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Color model (see RGB color 

model) 
Color table, 4-3 (see also 
Color map) 
index, 4-3 
Color value, 4-1, 4-3 

computation, 5-3 
Configuration, 2-3 (see also 
Display, configuration) 
Core graphics system, 1-1 
Current bitmap (see Bitmap, 

current) 
Current position 5-1, 

11-49 
Cursor , 

display mode, 7-2 
origin, 7-1, 11-113 
pattern, 7-1, 11-114 
position, 7-1, 11-115 
restrictions, 7-1 
size, 7-1 



Data structures, 

gra0iics map files, 12-2 

C, 9-1, C-1 

FORTRAN, 9-5, D-1 

Pascal, 9-1, B-1 
Data t^^s, 9-2 

C, 9-2, C-1 

Pascal, 9-2, B-1 

FORTRAN, 9-5, D-1 
Destination bitmap (see Bitmap, 

destination) 
Direct graphics in windows, 
8-1 

display memory, 8-4 

hidden display manory, 
8-4 

image redisplay, 8-4 

input, 8-3 
Direct mode (see Mode) 
Display, 

acquiring, 8-1, 11-11 

borrowing (see Mode, 
borrow-disply) 

clearing, 4-3, 11-24 

configuration, 2-1, 11-52 

environments, 2-1 

hidden, 2-2, 11-17 

landscape, 3-3 



monochromatic, 2-1 

portrait, 3-3 

releasing, 8-2, 11-95 

visible, 2-2 
Display driver, 1-2 
Display Manager, 1-2, 8-1 
Display memory, 2-2 
Display mode (see Mode) 
Drawing value, 5-2, 11-117 
Drawing (see also Filling) 

arc, 11-18 

box, 11-33 

circle, 11-22 

connected lines (see 
polyline) 

disconnected lines (see 
mulitline) 

lines, 5-2, 5-4, 11-79 

multiline, 5-6, 11-82 

polygon, 5-2, 11-88 

polyline, 5-5, 11-91 

spline, 
parametric, 11-138 
X, 11-139 
y, 11-140 



Error messages, 
GMF, 12-2 
GPR, 9-11 

Event, 7-3, 
button, 7-3, 11-32 
characters, 11-36 
count, 7-5, 11-41 
disabling, 7-4, 11-32 
enabling, 7-4, 11-35 
input stream, 7-5, 11-123 
keyboard, 7-3, 11-35 
keyset, 7-3, 11-35 
locator, 7-3 
puck, 7-3 
reporting, 7-4 
touchpad, 7-3 
types, 7-3, 11-35 
wait, 7-5, 11-28, 11-38 
window transition, 7-3 

Examples, 
bit block transfer, 10-3, 
bitmap pointer, 3-6 
bit plane mask, 10-6 
cursor origin, 7-2 
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cursor value computation, 5-2 
current position, 5-1 
direct mode, 8-6 
input devices, 10-9 
drawing, 

line, 5-2, 5-4 

multiline, 5-6 

polyline, 5-5 
escternal storage of bitmap, 

10-15 
filling, 5-4 
input devices, 10-9 
program, 

FORTRAN, 10-3 

Pascal, 8-6, 10-1, 

10-6, 10-9, 10-13, 10-15 
rubber banding, 10-13 
storing a bitmap, 10-15 
Exiting a program, 8-3, 8-5, 
10-13 



Fault, time-out, 8-2, 8-3 

Filling, 11-25 
circles, 11-23 
polygons, 5-3, 11-25 
rectangles, 5-3, 11-94 
trapezoids, 5-3, 11-144 
triangles, 5-3, 11-145 

Font, 3-9, 3-12, 11-134 
replicating, 11-98 

Font file, 11-80, 11-98 

FORTRAN, 

character set, 11-36 
data structures, 9-5 
data types, 9-5 
insert files, 9-1 
sample program, 10-3 

Frame mode (see Mode) 



GMF routines 

Giy!F_$CLOSE, 12-4 
Qr_$OOPy_PLANE, 12-5 
GMF_$CX)Py_SUBPLANE, 12-7 
GiyiF_$OPEN, 12-9 
GMF_$RESTORE_ELANE, 12-11 



GPR routines 

GPR_$AGQUIRE_DISELiAY, 

8-2, 11-11 
GPR_$ADDITIVE_BLT, 6-4, 

11-12 
GPR_ $ALLOCATE_ ATTRIBUTE. 

BLOCK, 3-11, 11-14 
GPR_$ALLOCATE_BITMAP, 3-4, 

11-15 
GPR_ $ALLOCATE_BITMAP_NC, 

11-16 
GPR_ $ALLOCATE_HE»LBI'EMAP, 

3-5, 11-17 
GPR_$ARQ_3P, 11-18 
GPR_ $ATTRIB11TE_ BLOCK , 

3-11, 11-19 
GPR_$BIT_BLT, 6-4, 11-20 
GER_$CIRCLE, 11-22 
GPR_$CIRCLE_ FILLED, 11-23 
GPR_$CLEAR, 4-3, 11-24 
GPR_$CLOSE_FILL_PG(^, 

5-3, 11-25 
GPR_ $CLOSE_RETURN_PG(»J, 

5-3, 11-26 
GPR_$OOLOR_ZOOM, 11-27 
GER_ $0CM:_EVENT_WAIT, 

7-5, 11-28 
GPR_ $DEALL0CATE_ATTRIBUTE_ 

BLOCK, 11-30 
GPR_ $DEALLOCATE_BITiyiAP, 

11-31 
GPR_$DISABLE_ INPUT, 7-4, 

11-32 
GPR_$DRAWLBOX, 11-33 
GPR_ $ENABLE_DIRECr_ ACCESS , 

3-6, 11-34 
GPR_$ENABLE_ INPUT, 7-4, 

8-3, 11-35 
GPR_$EVENT_WAIT, 11-38 
GPR_$PORCE_RELEASE, 11-40 
GPR_$GET_EC, 7-5, 11-41 
GPR_$INIT, 2-8, 3-4, 

11-42 
GPR_$I^Q_ BITMAP, 3-5, 11-45 
GPR_ $11^ BITMAP_DIMENSIONS , 

3-5, 11-46 
GPR_ $INQ_BI'IMAP_POINTER, 

3-6, 11-47 
GPEL $IN;I.BM_BIT_0FFSET, 

3-5, 11-49 
GPR_$Il^CHARACrER_WIDTH, 11-50 
GER_$INQ_GOLOR_MAP, 4-2, 

11-51 
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GPR.$I^a_CDNFIG, 11-52 
GPR_ $I]^a)N£?rRAINTS , 

11-53 
GPR_$INQl COORDINATE. 

ORIGIN, 11-54 
GPR_$I]SQ_CP, 11-55 
GPR_$INQ_ CURSOR, 11-56 
GPR_$INQ_DRAWLVALUE, 4-3, 

11-58 
GPR_$I1^FILL_BACKGRCXJND_VALUE, 11-59 
GPR_$INQl FILL. PATTERN, 11-60 
GPR_$INQ_FILL_ VALUE, 

4-3, 11-61 
GPU. $I]SQ_HORIZCMrAIi_ SPACING, 11-62 
GPR_ $IN3l IMAGING_F0RMAT , 

2-8, 11-63 
GPR_$INQ_LINE_PATTERN, 11-64 
GPR_$II^LINESTYLE, 11-65 
GPR_$INQ_RASTER_0PS, 11-66 
GPR_$II^SPACE_SIZE, 11-67 
GPR..$ir^TEXT, 5-9, 11-68 
GPR_$INQlTEXT_ EXTENT, 5-10, 

11-69 
GPR_$I]^TEXr_OFFSET, 5-10, 

11-71 
GPR_$INQlTEXT_PATH, 11-74 
GPR_$INQ_TEXT_VALUES, 4-3, 

5-10, 11-75 
GPR_$INQ_VIS_LIST, 8-3, 

11-76 
GPR_$I]^WINDOWLID, 3-5, 

11-78 
GPR_$LINE, 5-2, 5-4, 11-79 
GPR_$LQAD_PONT_FILE, 5-9, 

11-80 
GPR_$MOVE, 5-1, 11-81 
GPR_$MULTILINE, 5-6, 11-82 
GPR_.$MULTITRAPEZOID, 11-83 
GPR_$OPEN_BITiyiAP_FILE, 11-84 
GPR_$PGaSI_POLYLINE, 11-88 
GPR_$PIXEI^BLT, 6-4, 11-89 
GPR_$POLYLINE , 5-5, 11-91 
GPR_$READ_ PIXELS, 4-7, 

11-92 
GPR_$RECrANGLE, 5-7, 11-94 
GPR_$RELEA5E_DISPLAy. 8-2, 

11-95 
GPR_ $REMAP_O0LOR_MEM0RY, 

11-96 
GPR_ $REMAP_00L0R_MEM0RY_1 , 

11-97 
GPR_$REPLICATE_K)NT, 11-98 



GPIL$SELECr_G0LOR^FRAME, | 

11-99 
GPR_ $SET_AOQ_TIiyE_OUT, 

11-100 
GPR_$SET_ ATTRIBUTE BLOCK, 

3-11, 11-101 
GPR_ $SET_AUTCLREFRESH , 

8-4, 11-102 
GPR_$SET^BITMAP, 3-4, 3-7, 

11-103 
GPR_$SET_BITMAP_DIMENSIONS, 

3-5, 11-104 
GPR__$SET_CEIARACrER_WIDTH, 11-106 
GPR_ $SET_CLIPPING_ ACTIVE, 

3-8, 11-107 
GPR_$SET_CLIP_WINDOW, 3-8, 

8-4, 11-108 
GPR_$SET_OOLOR_iyiAP, 2-9, 

4-2, 4-4, 11-110 
GPR_ $SET_G0ORDINATE_ 

ORIGIN, 3-2, 11-111 
GPR_ $SET_CURSOR_ ACTIVE , 

7-1, 11-112 
GPR_ $SET_CURSOR_ORIGIN, 

7-1, 7-2, 11-113 
GPR_$SET_CURSOR_ PATTERN, 

7-1, 11-114 ; 

GPR_ $SET_CURSOR_ POSITION, 

7-1, 7-2, 11-115 
GPR_$SET_DRAWL VALUE, 5-2, 

11-97 
GPR__$SET_FILL_BACKGROUND_VALUE, 11-118 
GPR_$SET_FILL_ PATTERN, 11-119 
GPR_$SET_FILL_VALUE, 4-3, 1-120 
GPR..$SET_H0RIZONTALu SPACING, 11-121 
GPR_$SET_IMAGING_FORMAT, ( 

2-8, 11-122 
GPR_$SET_INPUT..SID, 7-5, 

11-123 
GPR_$SET..LINE_PATrERN, 11-124 
GPR_$SET_LINESTyLE, 11-125 
GPR_ $SET..OBSCURED.OPT , 

11-126 
GPR_$SET^PLANE_iyiASK, 6-2, 

11-127 
GPR_$SET_RASTER_OP, 3-10, 

11-128 
GPR_ $SET_REFRESH_ENTRY, 

8-4, 11-130 
GPR_$SET_SPACE_SIZE, 11-132 
GPR_ $SET_TEXT_BACKGROUND_ 

VALUE, 4-3, 5-9, 11-133 i 
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GPR_$SET_TEXT_PONT, 5-9, 

11-134 
GER_$SET_TEXr_PATH, 11-135 
GPR_$SET_TEXT_VALUE, 4-3, 

5-9, 11-136 
GPR_$SET_WINDCWLID, 3-4, 

3-7, 11-137 
GPR_$SPLINE_CUBIC_P, 11-138 
GPR.$SHiINE_aBIC_X, 11-139 
GER_$SPLINE_CUBIC_Y, 11-140 

gpr_$start_k;c»i, ii-i4i 

GPR_$TERiyiINArE, 2-9, 3-4, 

11-142 
GPR_$TEXT, 5-10, 11-143 
GPR_$TRAPEZOID, 11-144 
GPR_$TRIANGLE, 11-145 
GPR_$UNLOAD_PONT_FILE, 5-9, 

11-146 
GPR.$WAIT_FRAME, 11-147 
GPR_$WRITE_ PIXELS, 2-9, 4-7, 
11-148 
Graphics block transfers 

(see BLT) 
Graphics map files, 
data structures, 12-2 
error messages, 12-2 
insert files, 12-2 
routines (see GMF 
routines) 
Graphics primitives, 
library, 1-1 
routines, 11-1 
Gray scale (see Intensity) 



H 



Hardware configuration (see 
Display, configuration) 

Hidden display memory, 2-2, 
8-4, 11-17 



Image redisplay, 8-4 
Imaging display format, 
initializing, 3-3 
using, 2-8, 11-122, 
11-63 
Initial bitmap, 3-1, 3-4 
Input device (see Input 
operations) 



Input operations, 7-5, 10-9 

(see also Event) 
Insert file, 
C, 9-1, C-1 
FORERAN, 9-1, D-1 
Pascal, 9-1, B-1 
Intensity, 4-1, 4-3 
Interactive display format, 
2-2 



K 



Keyboard, 

acquisition, 8-3, 11-32 
release, 8-3, 11-32 
event (see Event) 

Keyset, 7-4 



Landscape display, 2-1, 2-2, 3-3 
Line style (see 

Attributes) 
Lines, 5-2 (see also Drawing) 
Locator (see Event) 



M 



Memory, 

representation, 3-1 
refresh buffer, 2-6 

Mode, 

bor row-display, 2-6 

3-4, 10-17 
direct, 2-6, 3-4, 10-17 
frame, 2-7, 3-4, 10-18 
initializing, 11-42 
no-display, 2-7, 3-4, 
10-19 

Monochromatic display, 2-1 

Mouse, 10-9, 10-13 

Multiline (see Drawing) 

Multiple displayed bitmaps, 
character for, 3-7 
window identification 

for, 3-7, 11-78, 11-137 

Multiline (see Drawing) 
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N 



No-display mode (see Mode) 



Rectangle, 5-2, 11-94 
Redisplay, 8-4 
Restrictions, 2-7, 7-1 
RGB color model, 4-1 
RL±)ber banding, 10-3 



Picture element (see 

Pixel) 
Pixel, 2-1, 3-1 
format, 2-2 
position, 3-2 
read value, 11-92 
value, 3-2, 4-7 
write value, 11-148 
Plane, 3-1 
mask, 6-2, 10-6, 11-127 
of bitmap, 3-1 
Pointer, 3-6, 11-47 

bitmap storage, 3-5 
Polygons, 5-3, (see also 
Filling) 
rectangle, 5-2, 11-94 
trapezoid, 5-2, 11-144 
triangle, 5-2, 11-145 
Polyline, 5-5 (see also 

Drawing) 
Portrait display, 2-2 
Position, 
changing, 5-1 
current, 5-1 
Primitive, 1-1 
Program examples (see 

Examples, program) 
Puck (see Event, puck) 



R 



Raster operation, 3-10, 

11-66, 11-128 (see also 
Bitmap and Attributes) 

Raster unit, 3-2 



Scan line, 3-5 
Sm (display driver calls) 
1-2, 8-2 



Techniques, 10-1 
Text 

operations, 5-9 

(see also Attribute) 

path, 11-74 
Time-out, 8-2 
Touchpad (see Event) 
Trapezoid, 5-2, 11-144 
Triangle, 5-2, 11-145 



W 



Window, 

and direct graphics, 8-1 
clearing, 11-24 
identification, 3-7, 11-78, 

11-137 
obscured, 8-3 
Writing to display, 4-7, 
11-148 
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READER'S RESPONSE 

We use readers' comments in revising and improving our documents. 

Document Title: Programmer's Guide to DOMAIN Graphics Primitives 

First Printing: October, 1983 
Latest Printing: May, 1984 

What is the best feature of this manual? 



Please list any errors, emissions, or problem areas in the manual. 
(Identify errors by page, section, figure, or table number wherever 
possible.) 



What t^fpe of user are you? 

iSystems programmer; language 



i^lications programmer; language 

Student programmer 

User with little programming experience 

How often do you use your system? 



Nature of your work on the DOMAIN System:. 



Your name Date 



Organization 



Street Address 



City State Zip/Country 

No postage necessary if mailed in the U.S. Fold on dotted lines 
(see reverse side), tape, and mail. 



r 
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NO POSTAGE 

NECESSARY 

IF MAILED 

IN THE 

UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 100 CHELMSFORD, MA 01824 



POSTAGE WILL BE PAID BY ADDRESSEE 



APOLLO COMPUTER, INC. 
16 Elizabeth Drive 
Chelmsford, MA 01824 

Attn.: Soflware Documentation 
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